2N/A@c %**start of header
2N/A@settitle GNU GRUB Manual @value{VERSION}
2N/A@c Unify all our little indices for now.
2N/A@footnotestyle separate
2N/AThis manual is for GNU GRUB (version @value{VERSION},
2N/ACopyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010 Free Software Foundation, Inc.
2N/APermission is granted to copy, distribute
and/or modify this document
2N/Aunder the terms of the GNU Free Documentation License, Version 1.2 or
2N/Aany later version published by the Free Software Foundation; with no
2N/A* GRUB: (grub). The GRand Unified Bootloader
2N/A* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
2N/A* grub-mkconfig: (grub)Invoking grub-mkconfig. Generate GRUB configuration
2N/A* grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
2N/A* grub-mkrescue: (grub)Invoking grub-mkrescue. Make a GRUB rescue image
2N/A@setchapternewpage odd
2N/A@title the GNU GRUB manual
2N/A@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
2N/A@author Gordon Matzigkeit
2N/A@author Yoshinori K. Okuji
2N/A@author Colin D. Bennett
2N/A@c The following two commands start the copyright page.
2N/A@vskip 0pt plus 1filll
2N/A@c Output the table of contents at the beginning.
2N/AThis is the documentation of GNU GRUB, the GRand Unified Bootloader,
2N/Aa flexible and powerful boot loader program for a wide range of
2N/AThis edition documents version @value{VERSION}.
2N/A* Introduction:: Capturing the spirit of GRUB
2N/A* Naming convention:: Names of your drives in GRUB
2N/A* Installation:: Installing GRUB on your drive
2N/A* Booting:: How to boot different operating systems
2N/A* Configuration:: Writing your own configuration file
2N/A* Theme file format:: Format of GRUB theme files
2N/A* Network:: Downloading OS images from a network
2N/A* Serial terminal:: Using GRUB via a serial line
2N/A* Vendor power-on keys:: Changing GRUB behaviour on vendor power-on keys
2N/A* Images:: GRUB image files
2N/A* Filesystem:: Filesystem syntax and semantics
2N/A* Interface:: The menu and the command-line
2N/A* Environment:: GRUB environment variables
2N/A* Commands:: The list of available builtin commands
2N/A* Internationalisation:: Topics relating to language support
2N/A* Security:: Authentication and authorisation
2N/A* Supported kernels:: The list of supported kernels
2N/A* Troubleshooting:: Error messages produced by GRUB
2N/A* Invoking grub-install:: How to use the GRUB installer
2N/A* Invoking grub-mkconfig:: Generate a GRUB configuration file
2N/A* Invoking grub-mkpasswd-pbkdf2::
2N/A Generate GRUB password hashes
2N/A* Invoking grub-mkrescue:: Make a GRUB rescue image
2N/A* Obtaining and Building GRUB:: How to obtain and build GRUB
2N/A* Reporting bugs:: Where you should send a bug report
2N/A* Future:: Some future plans on GRUB
2N/A* Copying This Manual:: Copying This Manual
2N/A@chapter Introduction to GRUB
2N/A* Overview:: What exactly GRUB is and how to use it
2N/A* History:: From maggot to house fly
2N/A* Changes from GRUB Legacy:: Differences from previous versions
2N/A* Features:: GRUB features
2N/A* Role of a boot loader:: The role of a boot loader
2N/ABriefly, a @dfn{boot loader} is the first software program that runs when
2N/Aa computer starts. It is responsible for loading and transferring
2N/Acontrol to an operating system @dfn{kernel} software (such as Linux or
2N/AGNU Mach). The kernel, in turn, initializes the rest of the operating
2N/AGNU GRUB is a very powerful boot loader, which can load a wide variety
2N/Aof free operating systems, as well as proprietary operating systems with
2N/Achain-loading@footnote{@dfn{chain-load} is the mechanism for loading
2N/Aunsupported operating systems by loading another boot loader. It is
2N/Atypically used for loading DOS or Windows.}. GRUB is designed to
2N/Aaddress the complexity of booting a personal computer; both the
2N/Aprogram and this manual are tightly bound to that computer platform,
2N/Aalthough porting to other platforms may be addressed in the future.
2N/AOne of the important features in GRUB is flexibility; GRUB understands
2N/Afilesystems and kernel executable formats, so you can load an arbitrary
2N/Aoperating system the way you like, without recording the physical
2N/Aposition of your kernel on the disk. Thus you can load the kernel
2N/Ajust by specifying its file name and the drive and partition where the
2N/AWhen booting with GRUB, you can use either a command-line interface
2N/A(@pxref{Command-line interface}), or a menu interface (@pxref{Menu
2N/Ainterface}). Using the command-line interface, you type the drive
2N/Aspecification and file name of the kernel manually. In the menu
2N/Ainterface, you just select an OS using the arrow keys. The menu is
2N/Abased on a configuration file which you prepare beforehand
2N/A(@pxref{Configuration}). While in the menu, you can switch to the
2N/Acommand-line mode, and vice-versa. You can even edit menu entries
2N/AIn the following chapters, you will learn how to specify a drive, a
2N/Apartition, and a file name (@pxref{Naming convention}) to GRUB, how to
2N/Ainstall GRUB on your drive (@pxref{Installation}), and how to boot your
2N/AOSes (@pxref{Booting}), step by step.
2N/A@section History of GRUB
2N/AGRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
2N/AHurd with the University of Utah's Mach 4 microkernel (now known as GNU
2N/AMach). Erich and Brian Ford designed the Multiboot Specification
2N/A(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
2N/ASpecification}), because they were determined not to add to the large
2N/Anumber of mutually-incompatible PC boot methods.
2N/AErich then began modifying the FreeBSD boot loader so that it would
2N/Aunderstand Multiboot. He soon realized that it would be a lot easier
2N/Ato write his own boot loader from scratch than to keep working on the
2N/AFreeBSD boot loader, and so GRUB was born.
2N/AErich added many features to GRUB, but other priorities prevented him
2N/Afrom keeping up with the demands of its quickly-expanding user base. In
2N/A1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
2N/Aofficial GNU package, and opened its development by making the latest
2N/Asources available via anonymous CVS. @xref{Obtaining and Building
2N/AGRUB}, for more information.
2N/AOver the next few years, GRUB was extended to meet many needs, but it
2N/Aquickly became clear that its design was not keeping up with the extensions
2N/Abeing made to it, and we reached the point where it was very difficult to
2N/Amake any further changes without breaking existing features. Around 2002,
2N/AYoshinori K. Okuji started work on PUPA (Preliminary Universal Programming
2N/AArchitecture for GNU GRUB), aiming to rewrite the core of GRUB to make it
2N/Acleaner, safer, more robust, and more powerful. PUPA was eventually renamed
2N/Ato GRUB 2, and the original version of GRUB was renamed to GRUB Legacy.
2N/ASmall amounts of maintenance continued to be done on GRUB Legacy, but the
2N/Alast release (0.97) was made in 2005 and at the time of writing it seems
2N/Aunlikely that there will be another.
2N/ABy around 2007,
GNU/Linux distributions started to use GRUB 2 to limited
2N/Aextents, and by the end of 2009 multiple major distributions were installing
2N/A@node Changes from GRUB Legacy
2N/A@section Differences from previous versions
2N/AGRUB 2 is a rewrite of GRUB (@pxref{History}), although it shares many
2N/Acharacteristics with the previous version, now known as GRUB Legacy. Users
2N/Aof GRUB Legacy may need some guidance to find their way around this new
2N/AThe configuration file has a new name (@file{
grub.cfg} rather than
2N/Amany new commands (@pxref{Commands}). Configuration cannot be copied over
2N/Adirectly, although most GRUB Legacy users should not find the syntax too
2N/A@command{grub-mkconfig} (@pxref{Simple configuration}). This makes it
2N/Aeasier to handle versioned kernel upgrades.
2N/APartition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming
2N/AThe configuration file is now written in something closer to a full
2N/Ascripting language: variables, conditionals, and loops are available.
2N/AA small amount of persistent storage is available across reboots, using the
2N/A@command{save_env} and @command{load_env} commands in GRUB and the
2N/A@command{grub-editenv} utility. This is not available in all configurations
2N/A(@pxref{Environment block}).
2N/AGRUB 2 has more reliable ways to find its own files and those of target
2N/Akernels on multiple-disk systems, and has commands (@pxref{search}) to find
2N/Adevices using file system labels or Universally Unique Identifiers (UUIDs).
2N/AGRUB 2 is available for several other types of system in addition to the PC
2N/ABIOS systems supported by GRUB Legacy: PC EFI, PC coreboot, PowerPC, SPARC,
2N/Aand MIPS Lemote Yeeloong are all supported.
2N/AMany more file systems are supported, including but not limited to ext4,
2N/AGRUB 2 can read files directly from LVM and RAID devices.
2N/AA graphical terminal and a graphical menu system are available.
2N/AGRUB 2's interface can be translated, including menu entry names.
2N/AThe image files (@pxref{Images}) that make up GRUB have been reorganised;
2N/AStage 1, Stage 1.5, and Stage 2 are no more.
2N/AGRUB 2 puts many facilities in dynamically loaded modules, allowing the core
2N/Aimage to be smaller, and allowing the core image to be built in more
2N/A@section GRUB features
2N/AThe primary requirement for GRUB is that it be compliant with the
2N/A@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
2N/ASpecification, Motivation, multiboot, The Multiboot Specification}.
2N/AThe other goals, listed in approximate order of importance, are:
2N/ABasic functions must be straightforward for end-users.
2N/ARich functionality to support kernel experts and designers.
2N/ABackward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
2N/ALinux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
2N/Asupported via a chain-loading function.
2N/AExcept for specific compatibility modes (chain-loading and the Linux
2N/A@dfn{piggyback} format), all kernels will be started in much the same
2N/Astate as in the Multiboot Specification. Only kernels loaded at 1 megabyte
2N/Aor above are presently supported. Any attempt to load below that
2N/Aboundary will simply result in immediate failure and an error message
2N/Areporting the problem.
2N/AIn addition to the requirements above, GRUB has the following features
2N/A(note that the Multiboot Specification doesn't require all the features
2N/A@item Recognize multiple executable formats
2N/ASupport many of the @dfn{
a.out} variants plus @dfn{ELF}. Symbol
2N/Atables are also loaded.
2N/A@item Support non-Multiboot kernels
2N/ASupport many of the various free 32-bit kernels that lack Multiboot
2N/Acompliance (primarily FreeBSD, NetBSD, OpenBSD, and
2N/ALinux). Chain-loading of other boot loaders is also supported.
2N/A@item Load multiples modules
2N/AFully support the Multiboot feature of loading multiple modules.
2N/A@item Load a configuration file
2N/ASupport a human-readable text configuration file with preset boot
2N/Acommands. You can also load another configuration file dynamically and
2N/Aembed a preset configuration file in a GRUB image file. The list of
2N/Acommands (@pxref{Commands}) are a superset of those supported on the
2N/Acommand-line. An example configuration file is provided in
2N/A@item Provide a menu interface
2N/AA menu interface listing preset boot commands, with a programmable
2N/Atimeout, is available. There is no fixed limit on the number of boot
2N/Aentries, and the current implementation has space for several hundred.
2N/A@item Have a flexible command-line interface
2N/AA fairly flexible command-line interface, accessible from the menu,
2N/Ais available to edit any preset commands, or write a new boot command
2N/Aset from scratch. If no configuration file is present, GRUB drops to
2N/AThe list of commands (@pxref{Commands}) are a subset of those supported
2N/Afor configuration files. Editing commands closely resembles the Bash
2N/Acommand-line (@pxref{Command Line Editing, Bash, Command Line Editing,
2N/Afeatures, Bash Features}), with @key{TAB}-completion of commands,
2N/Adevices, partitions, and files in a directory depending on context.
2N/A@item Support multiple filesystem types
2N/ASupport multiple filesystem types transparently, plus a useful explicit
2N/Ablocklist notation. The currently supported filesystem types are @dfn{Amiga
2N/AFast FileSystem (AFFS)}, @dfn{AtheOS fs}, @dfn{BeFS},
2N/A@dfn{BtrFS} (including raid0, raid1, raid10, gzip and lzo),
2N/A@dfn{cpio} (little- and big-endian bin, odc and newc variants),
2N/A@dfn{HFS+}, @dfn{ISO9660} (including Joliet, Rock-ridge and multi-chunk files),
2N/A@dfn{JFS}, @dfn{Minix fs} (versions 1, 2 and 3), @dfn{nilfs2},
2N/A@dfn{NTFS} (including compression), @dfn{ReiserFS}, @dfn{ROMFS},
2N/A@dfn{Amiga Smart FileSystem (SFS)}, @dfn{Squash4}, @dfn{tar}, @dfn{UDF},
2N/A@dfn{BSD
UFS/UFS2}, @dfn{XFS}, and @dfn{ZFS} (including lzjb, gzip,
2N/Azle, mirror, stripe, raidz1/2/3 and encryption in AES-CCM and AES-GCM).
2N/A@xref{Filesystem}, for more information.
2N/A@item Support automatic decompression
2N/ACan decompress files which were compressed by @command{gzip} or
2N/A@command{xz}@footnote{Only CRC32 data integrity check is supported (xz default
2N/Ais CRC64 so one should use --check=crc32 option). LZMA BCJ filters are
2N/Asupported.}. This function is both automatic and transparent to the user
2N/A(
i.e. all functions operate upon the uncompressed contents of the specified
2N/Afiles). This greatly reduces a file size and loading time, a
2N/Aparticularly great benefit for floppies.@footnote{There are a few
2N/Apathological cases where loading a very badly organized ELF kernel might
2N/Atake longer, but in practice this never happen.}
2N/AIt is conceivable that some kernel modules should be loaded in a
2N/Acompressed state, so a different module-loading command can be specified
2N/Ato avoid uncompressing the modules.
2N/A@item Access data on any installed device
2N/ASupport reading data from any or all floppies or hard disk(s) recognized
2N/Aby the BIOS, independent of the setting of the root device.
2N/A@item Be independent of drive geometry translations
2N/AUnlike many other boot loaders, GRUB makes the particular drive
2N/Atranslation irrelevant. A drive installed and running with one
2N/Atranslation may be converted to another translation without any adverse
2N/Aeffects or changes in GRUB's configuration.
2N/A@item Detect all installed @sc{ram}
2N/AGRUB can generally find all the installed @sc{ram} on a PC-compatible
2N/Amachine. It uses an advanced BIOS query technique for finding all
2N/Amemory regions. As described on the Multiboot Specification (@pxref{Top,
2N/AMultiboot Specification, Motivation, multiboot, The Multiboot
2N/ASpecification}), not all kernels make use of this information, but GRUB
2N/Aprovides it for those who do.
2N/A@item Support Logical Block Address mode
2N/AIn traditional disk calls (called @dfn{CHS mode}), there is a geometry
2N/Atranslation problem, that is, the BIOS cannot access over 1024
2N/Acylinders, so the accessible space is limited to at least 508 MB and to
2N/Aat most 8GB. GRUB can't universally solve this problem, as there is no
2N/Astandard interface used in all machines. However, several newer machines
2N/Ahave the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
2N/Aautomatically detects if LBA mode is available and uses it if
2N/Aavailable. In LBA mode, GRUB can access the entire disk.
2N/A@item Support network booting
2N/AGRUB is basically a disk-based boot loader but also has network
2N/Asupport. You can load OS images from a network by using the @dfn{TFTP}
2N/A@item Support remote terminals
2N/ATo support computers with no console, GRUB provides remote terminal
2N/Asupport, so that you can control GRUB from a remote host. Only serial
2N/Aterminal support is implemented at the moment.
2N/A@node Role of a boot loader
2N/A@section The role of a boot loader
2N/AThe following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
2N/ASome people like to acknowledge both the operating system and kernel when
2N/Athey talk about their computers, so they might say they use
2N/Akernel is the most important part of the system, so they like to call
2N/Atheir GNU operating systems ``Linux systems.''
2N/AI, personally, believe that this is a grave injustice, because the
2N/A@emph{boot loader} is the most important software of all. I used to
2N/Arefer to the above systems as either ``LILO''@footnote{The LInux LOader,
2N/Aa boot loader that everybody uses, but nobody likes.} or ``GRUB''
2N/AUnfortunately, nobody ever understood what I was talking about; now I
2N/Ajust use the word ``GNU'' as a pseudonym for GRUB.
2N/ASo, if you ever hear people talking about their alleged ``GNU'' systems,
2N/Aremember that they are actually paying homage to the best boot loader
2N/AWe, the GRUB maintainers, do not (usually) encourage Gordon's level of
2N/Afanaticism, but it helps to remember that boot loaders deserve
2N/Arecognition. We hope that you enjoy using GNU GRUB as much as we did
2N/A@node Naming convention
2N/A@chapter Naming convention
2N/AThe device syntax used in GRUB is a wee bit different from what you may
2N/Ahave seen before in your operating system(s), and you need to know it so
2N/ALook at the following examples and explanations:
2N/AFirst of all, GRUB requires that the device name be enclosed with
2N/A@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
2N/Adisk. The number @samp{0} is the drive number, which is counted from
2N/A@emph{zero}. This expression means that GRUB will use the whole floppy
2N/AHere, @samp{hd} means it is a hard disk drive. The first integer
2N/A@samp{0} indicates the drive number, that is, the first hard disk,
2N/Athe string @samp{msdos} indicates the partition scheme, while
2N/Athe second integer, @samp{2}, indicates the partition number (or the
2N/A@sc{pc} slice number in the BSD terminology). The partition numbers are
2N/Acounted from @emph{one}, not from zero (as was the case in previous
2N/Aversions of GRUB). This expression means the second partition of the
2N/Afirst hard disk drive. In this case, GRUB uses one partition of the
2N/Adisk, instead of the whole disk.
2N/AThis specifies the first @dfn{extended partition} of the first hard disk
2N/Adrive. Note that the partition numbers for extended partitions are
2N/Acounted from @samp{5}, regardless of the actual number of primary
2N/Apartitions on your hard disk.
2N/AThis means the BSD @samp{a} partition on first @sc{pc} slice number
2N/Aof the second hard disk.
2N/AOf course, to actually access the disks or partitions with GRUB, you
2N/Aneed to use the device specification in a command, like @samp{set
2N/Aroot=(fd0)} or @samp{parttool (hd0,msdos3) hidden-}. To help you find out
2N/Awhich number specifies a partition you want, the GRUB command-line
2N/A(@pxref{Command-line interface}) options have argument
2N/Acompletion. This means that, for example, you only need to type
2N/Afollowed by a @key{TAB}, and GRUB will display the list of drives,
2N/Apartitions, or file names. So it should be quite easy to determine the
2N/Aname of your target partition, even with minimal knowledge of the
2N/ANote that GRUB does @emph{not} distinguish IDE from SCSI - it simply
2N/Acounts the drive numbers from zero, regardless of their type. Normally,
2N/Aany IDE drive number is less than any SCSI drive number, although that
2N/Ais not true if you change the boot sequence by swapping IDE and SCSI
2N/ANow the question is, how to specify a file? Again, consider an
2N/AThis specifies the file named @samp{vmlinuz}, found on the first
2N/Apartition of the first hard disk drive. Note that the argument
2N/Acompletion works with file names, too.
2N/AThat was easy, admit it. Now read the next chapter, to find out how to
2N/Aactually install GRUB on your drive.
2N/A@chapter Installation
2N/AIn order to install GRUB as your boot loader, you need to first
2N/Ainstall the GRUB system and utilities under your UNIX-like operating
2N/Asystem (@pxref{Obtaining and Building GRUB}). You can do this either
2N/Afrom the source tarball, or as a package for your OS.
2N/AAfter you have done that, you need to install the boot loader on a
2N/Adrive (floppy or hard disk) by using the utility
2N/A@command{grub-install} (@pxref{Invoking grub-install}) on a UNIX-like OS.
2N/AGRUB comes with boot images, which are normally put in the directory
2N/Acalled the @dfn{image directory}, and the directory where the boot
2N/Aloader needs to find them (usually @file{/boot}) will be called
2N/Athe @dfn{boot directory}.
2N/A* Installing GRUB using grub-install::
2N/A* Making a GRUB bootable CD-ROM::
2N/A* BIOS installation::
2N/A@node Installing GRUB using grub-install
2N/A@section Installing GRUB using grub-install
2N/AFor information on where GRUB should be installed on PC BIOS platforms,
2N/A@pxref{BIOS installation}.
2N/AIn order to install GRUB under a UNIX-like OS (such
2N/Aas @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
2N/Agrub-install}) as the superuser (@dfn{root}).
2N/AThe usage is basically very simple. You only need to specify one
2N/Aargument to the program, namely, where to install the boot loader. The
2N/Aargument has to be either a device file (like @samp{
/dev/hda}).
2N/AFor example, under Linux the following will install GRUB into the MBR
2N/Aof the first IDE disk:
2N/ABut all the above examples assume that GRUB should put images under
2N/Athe @file{/boot} directory. If you want GRUB to put images under a directory
2N/Aother than @file{/boot}, you need to specify the option
2N/A@option{--boot-directory}. The typical usage is that you create a GRUB
2N/Aboot floppy with a filesystem. Here is an example:
2N/ASome BIOSes have a bug of exposing the first partition of a USB drive as a
2N/Afloppy instead of exposing the USB drive as a hard disk (they call it
2N/A``USB-FDD'' boot). In such cases, you need to install like this:
2N/AThis install doesn't conflict with standard install as long as they are in
2N/Aseparate directories.
2N/ANote that @command{grub-install} is actually just a shell script and the
2N/Areal task is done by @command{grub-mkimage} and @command{grub-setup}.
2N/ATherefore, you may run those commands directly to install GRUB, without
2N/Ausing @command{grub-install}. Don't do that, however, unless you are very
2N/Afamiliar with the internals of GRUB. Installing a boot loader on a running
2N/AOS may be extremely dangerous.
2N/A@node Making a GRUB bootable CD-ROM
2N/A@section Making a GRUB bootable CD-ROM
2N/AGRUB supports the @dfn{no emulation mode} in the El Torito
2N/Aspecification@footnote{El Torito is a specification for bootable CD
2N/Ausing BIOS functions.}. This means that you can use the whole CD-ROM
2N/Afrom GRUB and you don't have to make a floppy or hard disk image file,
2N/Awhich can cause compatibility problems.
2N/AFor booting from a CD-ROM, GRUB uses a special image called
2N/A@file{
core.img} used for this should be built with at least the
2N/A@samp{iso9660} and @samp{biosdisk} modules. Your bootable CD-ROM will
2N/Ausually also need to include a configuration file @file{
grub.cfg} and some
2N/ATo make a simple generic GRUB rescue CD, you can use the
2N/A@command{grub-mkrescue} program (@pxref{Invoking grub-mkrescue}):
2N/AYou will often need to include other files in your image. To do this, first
2N/Amake a top directory for the bootable image, say, @samp{iso}:
2N/AMake a directory for GRUB:
2N/A(@pxref{Configuration}), and copy any files and directories for the disc to the
2N/Adirectory @file{iso/}.
2N/AFinally, make the image:
2N/AThis produces a file named @file{
grub.iso}, which then can be burned
2N/Ainto a CD (or a DVD), or written to a USB mass storage device.
2N/AThe root device will be set up appropriately on entering your
2N/A@file{
grub.cfg} configuration file, so you can refer to file names on the CD
2N/Awithout needing to use an explicit device name. This makes it easier to
2N/Aproduce rescue images that will work on both optical drives and USB mass
2N/A@section The map between BIOS drives and OS devices
2N/AThe @command{grub-mkdevicemap} program can be used to create the @dfn{device
2N/Amap file}. It is often run automatically by tools such as
2N/A@command{grub-install} if the device map file does not already exist. The
2N/AIf the device map file exists, the GRUB utilities (@command{grub-probe},
2N/A@command{grub-setup}, etc.) read it to map BIOS drives to OS devices. This
2N/Afile consists of lines like this:
2N/A@var{device} @var{file}
2N/A@var{device} is a drive specified in the GRUB syntax (@pxref{Device
2N/Asyntax}), and @var{file} is an OS file, which is normally a device file.
2N/AHistorically, the device map file was used because GRUB device names had to
2N/Abe used in the configuration file, and they were derived from BIOS drive
2N/Anumbers. The map between BIOS drives and OS devices cannot always be
2N/Aguessed correctly: for example, GRUB will get the order wrong if you
2N/Aexchange the boot sequence between IDE and SCSI in your BIOS.
2N/AUnfortunately, even OS device names are not always stable. Modern versions
2N/Aof the Linux kernel may probe drives in a different order from boot to boot,
2N/Aon the driver subsystem in use. As a result, the device map file required
2N/Afrequent editing on some systems.
2N/AGRUB avoids this problem nowadays by using UUIDs or file system labels when
2N/Agenerating @file{
grub.cfg}, and we advise that you do the same for any
2N/Acustom menu entries you write. If the device map file does not exist, then
2N/Athe GRUB utilities will assume a temporary device map on the fly. This is
2N/Aoften good enough, particularly in the common case of single-disk systems.
2N/AHowever, the device map file is not entirely obsolete yet, and there are
2N/Astill some situations that require it to exist. If necessary, you may edit
2N/Athe file if @command{grub-mkdevicemap} makes a mistake. You can put any
2N/Acomments in the file if needed, as the GRUB utilities assume that a line is
2N/Ajust a comment if the first character is @samp{#}.
2N/A@node BIOS installation
2N/A@section BIOS installation
2N/AThe partition table format traditionally used on PC BIOS platforms is called
2N/Athe Master Boot Record (MBR) format; this is the format that allows up to
2N/Afour primary partitions and additional logical partitions. With this
2N/Apartition table format, there are two ways to install GRUB: it can be
2N/Aembedded in the area between the MBR and the first partition (called by
2N/Avarious names, such as the "boot track", "MBR gap", or "embedding area", and
2N/Awhich is usually at least 31 KiB), or the core image can be installed in a
2N/Afile system and a list of the blocks that make it up can be stored in the
2N/Afirst sector of that partition.
2N/AEach of these has different problems. There is no way to reserve space in
2N/Athe embedding area with complete safety, and some proprietary software is
2N/Aknown to use it to make it difficult for users to work around licensing
2N/Arestrictions; and systems are sometimes partitioned without leaving enough
2N/Aspace before the first partition. On the other hand, installing to a
2N/Afilesystem means that GRUB is vulnerable to its blocks being moved around by
2N/Afilesystem features such as tail packing, or even by aggressive fsck
2N/Aimplementations, so this approach is quite fragile; and this approach can
2N/Aonly be used if the @file{/boot} filesystem is on the same disk that the
2N/ABIOS boots from, so that GRUB does not have to rely on guessing BIOS drive
2N/AThe GRUB development team generally recommends embedding GRUB before the
2N/Afirst partition, unless you have special requirements. You must ensure that
2N/Athe first partition starts at least 31 KiB (63 sectors) from the start of
2N/Athe disk; on modern disks, it is often a performance advantage to align
2N/Apartitions on larger boundaries anyway, so the first partition might start 1
2N/AMiB from the start of the disk.
2N/ASome newer systems use the GUID Partition Table (GPT) format. This was
2N/Aspecified as part of the Extensible Firmware Interface (EFI), but it can
2N/Aalso be used on BIOS platforms if system software supports it; for example,
2N/AGRUB and
GNU/Linux can be used in this configuration. With this format, it
2N/Ais possible to reserve a whole partition for GRUB, called the BIOS Boot
2N/APartition. GRUB can then be embedded into that partition without the risk
2N/Aof being overwritten by other software and without being contained in a
2N/Afilesystem which might move its blocks around.
2N/AWhen creating a BIOS Boot Partition on a GPT system, you should make sure
2N/Athat it is at least 31 KiB in size. (GPT-formatted disks are not usually
2N/Aparticularly small, so we recommend that you make it larger than the bare
2N/Aminimum, such as 1 MiB, to allow plenty of room for growth.) You must also
2N/Amake sure that it has the proper partition type. Using GNU Parted, you can
2N/Aset this using a command such as the following:
2N/A# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
2N/AIf you are using gdisk, set the partition type to @samp{0xEF02}. With
2N/Apartitioning programs that require setting the GUID directly, it should be
2N/A@samp{21686148-6449-6e6f-744e656564454649}.
2N/A@strong{Caution:} Be very careful which partition you select! When GRUB
2N/Afinds a BIOS Boot Partition during installation, it will automatically
2N/Aoverwrite part of it. Make sure that the partition does not contain any
2N/AGRUB can load Multiboot-compliant kernels in a consistent way,
2N/Abut for some free operating systems you need to use some OS-specific
2N/A* General boot methods:: How to boot OSes with GRUB generally
2N/A* Loopback booting:: Notes on booting from loopbacks
2N/A* OS-specific notes:: Notes on some operating systems
2N/A@node General boot methods
2N/A@section How to boot operating systems
2N/AGRUB has two distinct boot methods. One of the two is to load an
2N/Aoperating system directly, and the other is to chain-load another boot
2N/Aloader which then will load an operating system actually. Generally
2N/Aspeaking, the former is more desirable, because you don't need to
2N/Ainstall or maintain other boot loaders and GRUB is flexible enough to
2N/Athe latter is sometimes required, since GRUB doesn't support all the
2N/Aexisting operating systems natively.
2N/A* Loading an operating system directly::
2N/A@node Loading an operating system directly
2N/A@subsection How to boot an OS directly with GRUB
2N/AMultiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
2N/AThe Multiboot Specification}) is the native format supported by GRUB.
2N/AFor the sake of convenience, there is also support for Linux, FreeBSD,
2N/ANetBSD and OpenBSD. If you want to boot other operating systems, you
2N/Awill have to chain-load them (@pxref{Chain-loading}).
2N/AFIXME: this section is incomplete.
2N/ARun the command @command{boot} (@pxref{boot}).
2N/AHowever, DOS and Windows have some deficiencies, so you might have to
2N/A@subsection Chain-loading an OS
2N/AOperating systems that do not support Multiboot and do not have specific
2N/Asupport in GRUB (specific support is available for Linux, FreeBSD, NetBSD
2N/Aand OpenBSD) must be chain-loaded, which involves loading another boot
2N/Aloader and jumping to it in real mode.
2N/AThe @command{chainloader} command (@pxref{chainloader}) is used to set this
2N/Aup. It is normally also necessary to load some GRUB modules and set the
2N/Aappropriate root device. Putting this together, we get something like this,
2N/Afor a Windows system on the first partition of the first hard disk:
2N/Amenuentry "Windows" {
2N/A@c FIXME: document UUIDs.
2N/AOn systems with multiple hard disks, an additional workaround may be
2N/AChain-loading is only supported on PC BIOS and EFI platforms.
2N/A@node Loopback booting
2N/A@section Loopback booting
2N/AGRUB is able to read from an image (be it one of CD or HDD) stored on
2N/Aany of its accessible storages (refer to @pxref{loopback} command).
2N/AHowever the OS itself should be able to find its root. This usually
2N/Ainvolves running a userspace program running before the real root
2N/Ais discovered. This is achieved by GRUB loading a specially made
2N/Asmall image and passing it as ramdisk to the kernel. This is achieved
2N/Aby commands @command{kfreebsd_module}, @command{knetbsd_module_elf},
2N/A@command{kopenbsd_ramdisk}, @command{initrd} (@pxref{initrd}),
2N/A@command{initrd16} (@pxref{initrd}), @command{multiboot_module},
2N/A@command{multiboot2_module} or @command{xnu_ramdisk}
2N/Adepending on the loader. Note that for knetbsd the image must be put
2N/Akopenbsd payload this is disabled by default. Aditionally behaviour of
2N/Ainitial ramdisk depends on command line options. Several distributors provide
2N/Athe image for this purpose or it's integrated in their standard ramdisk and
2N/Aactivated by special option. Consult your kernel and distribution manual for
2N/Amore details. Other loaders like appleloader, chainloader (BIOS, EFI, coreboot),
2N/Afreedos, ntldr and plan9 provide no possibility of loading initial ramdisk and
2N/Aas far as author is aware the payloads in question don't support either initial
2N/Aramdisk or discovering loopback boot in other way and as such not bootable this
2N/Away. Please consider alternative boot methods like copying all files
2N/Afrom the image to actual partition. Consult your OS documentation for
2N/A@node OS-specific notes
2N/A@section Some caveats on OS-specific issues
2N/AHere, we describe some caveats on several operating systems.
2N/ASince
GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
2N/Anothing special about it. But do not forget that you have to specify a
2N/Aroot partition to the kernel.
2N/ASet GRUB's root device to the same drive as
GNU/Hurd's. The command
2N/ALoad the kernel and the modules, like this:
2N/A --multiboot-command-line='$@{kernel-command-line@}' \
2N/A --host-priv-port='$@{host-port@}' \
2N/A --device-master-port='$@{device-port@}' \
2N/A --exec-server-task='$@{exec-task@}' -T typed '$@{root@}' \
2N/A '$(task-create)' '$(task-resume)'}
2N/AFinally, run the command @command{boot} (@pxref{boot}).
2N/AIt is relatively easy to boot
GNU/Linux from GRUB, because it somewhat
2N/Aresembles to boot a Multiboot-compliant OS.
2N/ASet GRUB's root device to the same drive as
GNU/Linux's. The command
2N/A@code{search --file --set /vmlinuz} or similar may help you
2N/ALoad the kernel using the command @command{linux} (@pxref{linux}):
2N/AIf you need to specify some kernel parameters, just append them to the
2N/Acommand. For example, to set @option{acpi} to @samp{off}, do this:
2N/ASee the documentation in the Linux source tree for complete information on
2N/Athe available options.
2N/AWith @command{linux} GRUB uses 32-bit protocol. Some BIOS services like APM
2N/Aor EDD aren't available with this protocol. In this case you need to use
2N/AIf you use an initrd, execute the command @command{initrd} (@pxref{initrd})
2N/Aafter @command{linux}:
2N/Agrub> @kbd{initrd /initrd}
2N/AIf you used @command{linux16} you need to use @command{initrd16}:
2N/Agrub> @kbd{initrd16 /initrd}
2N/AFinally, run the command @command{boot} (@pxref{boot}).
2N/A@strong{Caution:} If you use an initrd and specify the @samp{mem=}
2N/Aoption to the kernel to let it use less than actual memory size, you
2N/Awill also have to specify the same memory size to GRUB. To let GRUB know
2N/Athe size, run the command @command{uppermem} @emph{before} loading the
2N/Akernel. @xref{uppermem}, for more information.
2N/AGRUB cannot boot DOS or Windows directly, so you must chain-load them
2N/A(@pxref{Chain-loading}). However, their boot loaders have some critical
2N/Adeficiencies, so it may not work to just chain-load them. To overcome
2N/Athe problems, GRUB provides you with two helper functions.
2N/AIf you have installed DOS (or Windows) on a non-first hard disk, you
2N/Ahave to use the disk swapping technique, because that OS cannot boot
2N/Afrom any disks but the first one. The workaround used in GRUB is the
2N/Acommand @command{drivemap} (@pxref{drivemap}), like this:
2N/Adrivemap -s (hd0) (hd1)
2N/AThis performs a @dfn{virtual} swap between your first and second hard
2N/A@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
2N/Ato access the swapped disks. If that OS uses a special driver for the
2N/Adisks, this probably won't work.
2N/AAnother problem arises if you installed more than one set of
DOS/Windows 2N/Aonto one disk, because they could be confused if there are more than one
2N/Athis, but there is a solution if you do want to do so. Use the partition
2N/AIf GRUB @dfn{hides} a DOS (or Windows) partition (@pxref{parttool}), DOS (or
2N/AWindows) will ignore the partition. If GRUB @dfn{unhides} a DOS (or Windows)
2N/Apartition, DOS (or Windows) will detect the partition. Thus, if you have
2N/Ainstalled DOS (or Windows) on the first and the second partition of the
2N/Afirst hard disk, and you want to boot the copy on the first partition, do
2N/Aparttool (hd0,1) hidden-
2N/Aparttool (hd0,2) hidden+
2N/Aparttool @verb{'${root}'} boot+
2N/A@chapter Writing your own configuration file
2N/AGRUB is configured using @file{
grub.cfg}, usually located under
2N/A@file{
/boot/grub}. This file is quite flexible, but most users will not
2N/Aneed to write the whole thing by hand.
2N/A* Simple configuration:: Recommended for most users
2N/A* Shell-like scripting:: For power users and developers
2N/A* Embedded configuration:: Embedding a configuration file into GRUB
2N/A@node Simple configuration
2N/A@section Simple configuration handling
2N/AThe program @command{grub-mkconfig} (@pxref{Invoking grub-mkconfig})
2N/Agenerates @file{
grub.cfg} files suitable for most cases. It is suitable for
2N/Ause when upgrading a distribution, and will discover available kernels and
2N/Aattempt to generate menu entries for them.
2N/A@command{grub-mkconfig} does have some limitations. While adding extra
2N/Acustom menu entries to the end of the list can be done by editing
2N/Achanging the order of menu entries or changing their titles may require
2N/Amaking complex changes to shell scripts stored in @file{
/etc/grub.d/}. This
2N/Amay be improved in the future. In the meantime, those who feel that it
2N/Awould be easier to write @file{
grub.cfg} directly are encouraged to do so
2N/A(@pxref{Booting}, and @ref{Shell-like scripting}), and to disable any system
2N/Aprovided by their distribution to automatically run @command{grub-mkconfig}.
2N/A@command{grub-mkconfig}. It is sourced by a shell script, and so must be
2N/Avalid POSIX shell input; normally, it will just be a sequence of
2N/A@samp{KEY=value} lines, but if the value contains spaces or other special
2N/Acharacters then it must be quoted. For example:
2N/AGRUB_TERMINAL_INPUT="console serial"
2N/AThe default menu entry. This may be a number, in which case it identifies
2N/Athe Nth entry in the generated menu counted from zero, or the title of a
2N/Amenu entry, or the special string @samp{saved}. Using the title may be
2N/Auseful if you want to set a menu entry as the default even though there may
2N/Abe a variable number of entries before it.
2N/AFor example, if you have:
2N/Amenuentry 'Example
GNU/Linux distribution' --class gnu-linux {
2N/Athen you can make this the default using:
2N/AIf you set this to @samp{saved}, then the default menu entry will be that
2N/Asaved by @samp{GRUB_SAVEDEFAULT}, @command{grub-set-default}, or
2N/A@command{grub-reboot}.
2N/AThe default is @samp{0}.
2N/A@item GRUB_SAVEDEFAULT
2N/AIf this option is set to @samp{true}, then, when an entry is selected, save
2N/Ait as a new default entry for use by future runs of GRUB. This is only
2N/Auseful if @samp{GRUB_DEFAULT=saved}; it is a separate option because
2N/A@samp{GRUB_DEFAULT=saved} is useful without this option, in conjunction with
2N/A@command{grub-set-default} or @command{grub-reboot}. Unset by default.
2N/AThis option relies on the environment block, which may not be available in
2N/Aall situations (@pxref{Environment block}).
2N/ABoot the default entry this many seconds after the menu is displayed, unless
2N/Aa key is pressed. The default is @samp{5}. Set to @samp{0} to boot
2N/Aimmediately without displaying the menu, or to @samp{-1} to wait
2N/A@item GRUB_HIDDEN_TIMEOUT
2N/AWait this many seconds for a key to be pressed before displaying the menu.
2N/AIf no key is pressed during that time, boot immediately. Unset by default.
2N/A@item GRUB_HIDDEN_TIMEOUT_QUIET
2N/AIn conjunction with @samp{GRUB_HIDDEN_TIMEOUT}, set this to @samp{true} to
2N/Asuppress the verbose countdown while waiting for a key to be pressed before
2N/Adisplaying the menu. Unset by default.
2N/A@item GRUB_DEFAULT_BUTTON
2N/A@itemx GRUB_TIMEOUT_BUTTON
2N/A@itemx GRUB_HIDDEN_TIMEOUT_BUTTON
2N/A@itemx GRUB_BUTTON_CMOS_ADDRESS
2N/AVariants of the corresponding variables without the @samp{_BUTTON} suffix,
2N/Aused to support vendor-specific power buttons. @xref{Vendor power-on keys}.
2N/A@item GRUB_DISTRIBUTOR
2N/ASet by distributors of GRUB to their identifying name. This is used to
2N/Agenerate more informative menu entry titles.
2N/A@item GRUB_TERMINAL_INPUT
2N/ASelect the terminal input device. You may select multiple devices here,
2N/AValid terminal input names depend on the platform, but may include
2N/A@samp{console} (PC BIOS and EFI consoles), @samp{serial} (serial terminal),
2N/A@samp{ofconsole} (Open Firmware console), @samp{at_keyboard} (PC AT
2N/Akeyboard, mainly useful with Coreboot), or @samp{usb_keyboard} (USB keyboard
2N/Ausing the HID Boot Protocol, for cases where the firmware does not handle
2N/AThe default is to use the platform's native terminal input.
2N/A@item GRUB_TERMINAL_OUTPUT
2N/ASelect the terminal output device. You may select multiple devices here,
2N/AValid terminal output names depend on the platform, but may include
2N/A@samp{console} (PC BIOS and EFI consoles), @samp{serial} (serial terminal),
2N/A@samp{gfxterm} (graphics-mode output), @samp{ofconsole} (Open Firmware
2N/Aconsole), or @samp{vga_text} (VGA text output, mainly useful with Coreboot).
2N/AThe default is to use the platform's native terminal output.
2N/AIf this option is set, it overrides both @samp{GRUB_TERMINAL_INPUT} and
2N/A@samp{GRUB_TERMINAL_OUTPUT} to the same value.
2N/A@item GRUB_SERIAL_COMMAND
2N/AA command to configure the serial port when using the serial console.
2N/A@xref{serial}. Defaults to @samp{serial}.
2N/A@item GRUB_CMDLINE_LINUX
2N/ACommand-line arguments to add to menu entries for the Linux kernel.
2N/A@item GRUB_CMDLINE_LINUX_DEFAULT
2N/AUnless @samp{GRUB_DISABLE_RECOVERY} is set to @samp{true}, two menu
2N/Aentries will be generated for each Linux kernel: one default entry and one
2N/Aentry for recovery mode. This option lists command-line arguments to add
2N/Aonly to the default menu entry, after those listed in
2N/A@samp{GRUB_CMDLINE_LINUX}.
2N/A@item GRUB_CMDLINE_NETBSD
2N/A@itemx GRUB_CMDLINE_NETBSD_DEFAULT
2N/AAs @samp{GRUB_CMDLINE_LINUX} and @samp{GRUB_CMDLINE_LINUX_DEFAULT}, but for
2N/A@item GRUB_CMDLINE_XEN
2N/A@itemx GRUB_CMDLINE_XEN_DEFAULT
2N/AThe values of these options are appended to the values of
2N/A@samp{GRUB_CMDLINE_LINUX} and @samp{GRUB_CMDLINE_LINUX_DEFAULT} for Linux
2N/Aand Xen menu entries.
2N/A@item GRUB_CMDLINE_LINUX_XEN_REPLACE
2N/A@item GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT
2N/AThe values of these options replace the values of @samp{GRUB_CMDLINE_LINUX}
2N/Aand @samp{GRUB_CMDLINE_LINUX_DEFAULT} for Linux and Xen menu entries.
2N/A@item GRUB_DISABLE_LINUX_UUID
2N/ANormally, @command{grub-mkconfig} will generate menu entries that use
2N/Auniversally-unique identifiers (UUIDs) to identify the root filesystem to
2N/Athe Linux kernel, using a @samp{root=UUID=...} kernel parameter. This is
2N/Ausually more reliable, but in some cases it may not be appropriate. To
2N/Adisable the use of UUIDs, set this option to @samp{true}.
2N/A@item GRUB_DISABLE_RECOVERY
2N/AIf this option is set to @samp{true}, disable the generation of recovery
2N/A@item GRUB_VIDEO_BACKEND
2N/AIf graphical video support is required, either because the @samp{gfxterm}
2N/Agraphical terminal is in use or because @samp{GRUB_GFXPAYLOAD_LINUX} is set,
2N/Athen @command{grub-mkconfig} will normally load all available GRUB video
2N/Adrivers and use the one most appropriate for your hardware. If you need to
2N/Aoverride this for some reason, then you can set this option.
2N/AAfter @command{grub-install} has been run, the available video drivers are
2N/ASet the resolution used on the @samp{gfxterm} graphical terminal. Note that
2N/Ayou can only use modes which your graphics card supports via VESA BIOS
2N/AExtensions (VBE), so for example native LCD panel resolutions may not be
2N/Aavailable. The default is @samp{auto}, which tries to select a preferred
2N/Aresolution. @xref{gfxmode}.
2N/A@item GRUB_BACKGROUND
2N/ASet a background image for use with the @samp{gfxterm} graphical terminal.
2N/AThe value of this option must be a file readable by GRUB at boot time, and
2N/Ait must end with @file{.png}, @file{.tga}, @file{.jpg}, or @file{.jpeg}.
2N/AThe image will be scaled if necessary to fit the screen.
2N/ASet a theme for use with the @samp{gfxterm} graphical terminal.
2N/A@item GRUB_GFXPAYLOAD_LINUX
2N/ASet to @samp{text} to force the Linux kernel to boot in normal text mode,
2N/A@samp{keep} to preserve the graphics mode set using @samp{GRUB_GFXMODE},
2N/A@samp{@var{width}x@var{height}}[@samp{x@var{depth}}] to set a particular
2N/Agraphics mode, or a sequence of these separated by commas or semicolons to
2N/Atry several modes in sequence. @xref{gfxpayload}.
2N/ADepending on your kernel, your distribution, your graphics card, and the
2N/Aphase of the moon, note that using this option may cause
GNU/Linux to suffer
2N/Afrom various display problems, particularly during the early part of the
2N/Aboot sequence. If you have problems, set this option to @samp{text} and
2N/AGRUB will tell Linux to boot in normal text mode.
2N/A@item GRUB_DISABLE_OS_PROBER
2N/ANormally, @command{grub-mkconfig} will try to use the external
2N/A@command{os-prober} program, if installed, to discover other operating
2N/Asystems installed on the same system and generate appropriate menu entries
2N/Afor them. Set this option to @samp{true} to disable this.
2N/APlay a tune on the speaker when GRUB starts. This is particularly useful
2N/Afor users unable to see the screen. The value of this option is passed
2N/Adirectly to @ref{play}.
2N/AIf this option is set, GRUB will issue a @ref{badram} command to filter
2N/Aout specified regions of RAM.
2N/A@item GRUB_PRELOAD_MODULES
2N/AThis option may be set to a list of GRUB module names separated by spaces.
2N/AEach module will be loaded as early as possible, at the start of
2N/AFor more detailed customisation of @command{grub-mkconfig}'s output, you may
2N/A@file{
/etc/grub.d/40_custom} is particularly useful for adding entire custom
2N/Amenu entries; simply type the menu entries you want to add at the end of
2N/Athat file, making sure to leave at least the first two lines intact.
2N/A@node Shell-like scripting
2N/A@section Writing full configuration files directly
2N/A@c Some of this section is derived from the GNU Bash manual page, also
2N/A@c copyrighted by the FSF.
2N/A@file{
grub.cfg} is written in GRUB's built-in scripting language, which has
2N/Aa syntax quite similar to that of GNU Bash and other Bourne shell
2N/AA @dfn{word} is a sequence of characters considered as a single unit by
2N/AGRUB. Words are separated by @dfn{metacharacters}, which are the following
2N/Aplus space, tab, and newline:
2N/AQuoting may be used to include metacharacters in words; see below.
2N/A@heading Reserved words
2N/AReserved words have a special meaning to GRUB. The following words are
2N/Arecognised as reserved when unquoted and either the first word of a simple
2N/Acommand or the third word of a @code{for} command:
2N/Acase do done elif else esac fi for function
2N/Aif in menuentry select then time until while
2N/ANot all of these reserved words have a useful purpose yet; some are reserved
2N/Afor future expansion.
2N/AQuoting is used to remove the special meaning of certain characters or
2N/Awords. It can be used to treat metacharacters as part of a word, to prevent
2N/Areserved words from being recognised as such, and to prevent variable
2N/AThere are three quoting mechanisms: the escape character, single quotes, and
2N/AA non-quoted backslash (\) is the @dfn{escape character}. It preserves the
2N/Aliteral value of the next character that follows, with the exception of
2N/AEnclosing characters in single quotes preserves the literal value of each
2N/Acharacter within the quotes. A single quote may not occur between single
2N/Aquotes, even when preceded by a backslash.
2N/AEnclosing characters in double quotes preserves the literal value of all
2N/Acharacters within the quotes, with the exception of @samp{$} and @samp{\}.
2N/AThe @samp{$} character retains its special meaning within double quotes.
2N/AThe backslash retains its special meaning only when followed by one of the
2N/Afollowing characters: @samp{$}, @samp{"}, @samp{\}, or newline. A
2N/Abackslash-newline pair is treated as a line continuation (that is, it is
2N/Aremoved from the input stream and effectively ignored@footnote{Currently a
2N/Abackslash-newline pair within a variable name is not handled properly, so
2N/Ause this feature with some care.}). A double quote may be quoted within
2N/Adouble quotes by preceding it with a backslash.
2N/A@heading Variable expansion
2N/AThe @samp{$} character introduces variable expansion. The variable name to
2N/Abe expanded may be enclosed in braces, which are optional but serve to
2N/Aprotect the variable to be expanded from characters immediately following it
2N/Awhich could be interpreted as part of the name.
2N/ANormal variable names begin with an alphabetic character, followed by zero
2N/Aor more alphanumeric characters. These names refer to entries in the GRUB
2N/Aenvironment (@pxref{Environment}).
2N/APositional variable names consist of one or more digits. They represent
2N/Aparameters passed to function calls, with @samp{$1} representing the first
2N/Aparameter, and so on.
2N/AThe special variable name @samp{?} expands to the exit status of the most
2N/Arecently executed command. When positional variable names are active, other
2N/Aspecial variable names @samp{@@}, @samp{*} and @samp{#} are defined and they
2N/Aexpand to all positional parameters with necessary quoting, positional
2N/Aparameters without any quoting, and positional parameter count respectively.
2N/AA word beginning with @samp{#} causes that word and all remaining characters
2N/Aon that line to be ignored.
2N/A@heading Simple commands
2N/AA @dfn{simple command} is a sequence of words separated by spaces or tabs
2N/Aand terminated by a semicolon or a newline. The first word specifies the
2N/Acommand to be executed. The remaining words are passed as arguments to the
2N/AThe return value of a simple command is its exit status. If the reserved
2N/Aword @code{!} precedes the command, then the return value is instead the
2N/Alogical negation of the command's exit status.
2N/A@heading Compound commands
2N/AA @dfn{compound command} is one of the following:
2N/A@item for @var{name} in @var{word} @dots{}; do @var{list}; done
2N/AThe list of words following @code{in} is expanded, generating a list of
2N/Aitems. The variable @var{name} is set to each element of this list in turn,
2N/Aand @var{list} is executed each time. The return value is the exit status
2N/Aof the last command that executes. If the expansion of the items following
2N/A@code{in} results in an empty list, no commands are executed, and the return
2N/A@item if @var{list}; then @var{list}; [elif @var{list}; then @var{list};] @dots{} [else @var{list};] fi
2N/AThe @code{if} @var{list} is executed. If its exit status is zero, the
2N/A@code{then} @var{list} is executed. Otherwise, each @code{elif} @var{list}
2N/Ais executed in turn, and if its exit status is zero, the corresponding
2N/A@code{then} @var{list} is executed and the command completes. Otherwise,
2N/Athe @code{else} @var{list} is executed, if present. The exit status is the
2N/Aexit status of the last command executed, or zero if no condition tested
2N/A@item while @var{cond}; do @var{list}; done
2N/A@itemx until @var{cond}; do @var{list}; done
2N/AThe @code{while} command continuously executes the @code{do} @var{list} as
2N/Along as the last command in @var{cond} returns an exit status of zero. The
2N/A@code{until} command is identical to the @code{while} command, except that
2N/Athe test is negated; the @code{do} @var{list} is executed as long as the
2N/Alast command in @var{cond} returns a non-zero exit status. The exit status
2N/Aof the @code{while} and @code{until} commands is the exit status of the last
2N/A@code{do} @var{list} command executed, or zero if none was executed.
2N/A@item function @var{name} @{ @var{command}; @dots{} @}
2N/AThis defines a function named @var{name}. The @dfn{body} of the function is
2N/Athe list of commands within braces, each of which must be terminated with a
2N/Asemicolon or a newline. This list of commands will be executed whenever
2N/A@var{name} is specified as the name of a simple command. Function
2N/Adefinitions do not affect the exit status in @code{$?}. When executed, the
2N/Aexit status of a function is the exit status of the last command executed in
2N/A@item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--hotkey=key}] @{ @var{command}; @dots{} @}
2N/A@heading Built-in Commands
2N/ASome built-in commands are also provided by GRUB script to help script
2N/Awriters perform actions that are otherwise not possible. For example, these
2N/Ainclude commands to jump out of a loop without fully completing it, etc.
2N/A@item break [@code{n}]
2N/AExit from within a @code{for}, @code{while}, or @code{until} loop. If
2N/A@code{n} is specified, break @code{n} levels. @code{n} must be greater than
2N/Aor equal to 1. If @code{n} is greater than the number of enclosing loops,
2N/Aall enclosing loops are exited. The return value is 0 unless @code{n} is
2N/Anot greater than or equal to 1.
2N/A@item continue [@code{n}]
2N/AResume the next iteration of the enclosing @code{for}, @code{while} or
2N/A@code{until} loop. If @code{n} is specified, resume at the @code{n}th
2N/Aenclosing loop. @code{n} must be greater than or equal to 1. If @code{n}
2N/Ais greater than the number of enclosing loops, the last enclosing loop (the
2N/A@dfn{top-level} loop) is resumed. The return value is 0 unless @code{n} is
2N/Anot greater than or equal to 1.
2N/A@item return [@code{n}]
2N/ACauses a function to exit with the return value specified by @code{n}. If
2N/A@code{n} is omitted, the return status is that of the last command executed
2N/Ain the function body. If used outside a function the return status is
2N/A@item shift [@code{n}]
2N/AThe positional parameters from @code{n}+1 @dots{} are renamed to
2N/A@code{$1}@dots{}. Parameters represented by the numbers @code{$#} down to
2N/A@code{$#}-@code{n}+1 are unset. @code{n} must be a non-negative number less
2N/Athan or equal to @code{$#}. If @code{n} is 0, no parameters are changed.
2N/AIf @code{n} is not given, it is assumed to be 1. If @code{n} is greater
2N/Athan @code{$#}, the positional parameters are not changed. The return
2N/Astatus is greater than zero if @code{n} is greater than @code{$#} or less
2N/Athan zero; otherwise 0.
2N/A@node Embedded configuration
2N/A@section Embedding a configuration file into GRUB
2N/AGRUB supports embedding a configuration file directly into the core image,
2N/Aso that it is loaded before entering normal mode. This is useful, for
2N/Aexample, when it is not straightforward to find the real configuration file,
2N/Aor when you need to debug problems with loading that file.
2N/A@command{grub-install} uses this feature when it is not using BIOS disk
2N/Afunctions or when installing to a different disk from the one containing
2N/A@file{
/boot/grub}, in which case it needs to use the @command{search}
2N/ATo embed a configuration file, use the @option{-c} option to
2N/A@command{grub-mkimage}. The file is copied into the core image, so it may
2N/Areside anywhere on the file system, and may be removed after running
2N/A@command{grub-mkimage}.
2N/AAfter the embedded configuration file (if any) is executed, GRUB will load
2N/Athe @samp{normal} module (@pxref{normal}), which will then read the real
2N/A@code{root} variable will also have been set to the root device name. For
2N/Aexample, @code{prefix} might be set to @samp{(hd0,1)
/boot/grub}, and
2N/A@code{root} might be set to @samp{hd0,1}. Thus, in most cases, the embedded
2N/Aconfiguration file only needs to set the @code{prefix} and @code{root}
2N/Avariables, and then drop through to GRUB's normal processing. A typical
2N/Aexample of this might look like this:
2N/A(The @samp{search_fs_uuid} module must be included in the core image for this
2N/AIn more complex cases, it may be useful to read other configuration files
2N/Adirectly from the embedded configuration file. This allows such things as
2N/Areading files not called @file{
grub.cfg}, or reading files from a directory
2N/Aother than that where GRUB's loadable modules are installed. To do this,
2N/Ainclude the @samp{configfile} and @samp{normal} modules in the core image,
2N/Aand embed a configuration file that uses the @command{configfile} command to
2N/Aload another file. The following example of this also requires the
2N/A@command{echo}, @command{search_label}, and @command{test} modules to be
2N/Aincluded in the core image:
2N/A echo "Could not find an example configuration file!"
2N/AThe embedded configuration file may not contain menu entries directly, but
2N/Amay only read them from elsewhere using @command{configfile}.
2N/A@node Theme file format
2N/A@chapter Theme file format
2N/A@section Introduction
2N/AThe GRUB graphical menu supports themes that can customize the layout and
2N/Aappearance of the GRUB boot menu. The theme is configured through a plain
2N/Atext file that specifies the layout of the various GUI components (including
2N/Athe boot menu, timeout progress bar, and text messages) as well as the
2N/A@section Theme Elements
2N/AColors can be specified in several ways:
2N/A@item HTML-style ``#RRGGBB'' or ``#RGB'' format, where *R*, *G*, and *B* are hexadecimal digits (
e.g., ``#8899FF'')
2N/A@item as comma-separated decimal RGB values (
e.g., ``128, 128, 255'')
2N/A@item with ``SVG 1.0 color names'' (
e.g., ``cornflowerblue'') which must be specified in lowercase.
2N/AThe fonts GRUB uses ``PFF2 font format'' bitmap fonts. Fonts are specified
2N/Awith full font names. Currently there is no
2N/Aprovision for a preference list of fonts, or deriving one font from another.
2N/AFonts are loaded with the ``loadfont'' command in GRUB. To see the list of
2N/Aloaded fonts, execute the ``lsfonts'' command. If there are too many fonts to
2N/Afit on screen, do ``set pager=1'' before executing ``lsfonts''.
2N/A@subsection Progress Bar
2N/A@float Figure, Pixmap-styled progress bar
2N/A@c @image{Theme_progress_bar,,,,.png}
2N/A@float Figure, Plain progress bar, drawn with solid color.
2N/A@c @image{Theme_progress_bar_filled,,,,.png}
2N/AProgress bars are used to display the remaining time before GRUB boots the
2N/Adefault menu entry. To create a progress bar that will display the remaining
2N/Atime before automatic boot, simply create a ``progress_bar'' component with
2N/Athe id ``__timeout__''. This indicates to GRUB that the progress bar should
2N/Abe updated as time passes, and it should be made invisible if the countdown to
2N/Aautomatic boot is interrupted by the user.
2N/AProgress bars may optionally have text displayed on them. This is controlled
2N/Athrough the ``show_text'' property, which can be set to either ``true'' or
2N/A``false'' to control whether text is displayed. When GRUB is counting down to
2N/Aautomatic boot, the text informs the user of the number of seconds remaining.
2N/A@subsection Circular Progress Indicator
2N/A@c @image{Theme_circular_progress,,,,.png}
2N/AThe circular progress indicator functions similarly to the progress bar. When
2N/Agiven an id of ``__timeout__'', GRUB updates the circular progress indicator's
2N/Avalue to indicate the time remaining. For the circular progress indicator,
2N/Athere are two images used to render it: the *center* image, and the *tick*
2N/Aimage. The center image is rendered in the center of the component, while the
2N/Atick image is used to render each mark along the circumference of the
2N/AText labels can be placed on the boot screen. The font, color, and horizontal
2N/Aalignment can be specified for labels. If a label is given the id
2N/A``__timeout__'', then the ``text'' property for that label is also updated
2N/Awith a message informing the user of the number of seconds remaining until
2N/Aautomatic boot. This is useful in case you want the text displayed somewhere
2N/Aelse instead of directly on the progress bar.
2N/A@subsection Boot Menu
2N/A@c @image{Theme_boot_menu,,,,.png}
2N/AThe boot menu where GRUB displays the menu entries from the ``
grub.cfg'' file.
2N/AIt is a list of items, where each item has a title and an optional icon. The
2N/Aicon is selected based on the *classes* specified for the menu entry. If
2N/Adirectory, it will be displayed for items which have the class *myclass*. The
2N/Aboot menu can be customized in several ways, such as the font and color used
2N/Afor the menu entry title, and by specifying styled boxes for the menu itself
2N/Aand for the selected item highlight.
2N/A@subsection Styled Boxes
2N/AOne of the most important features for customizing the layout is the use of
2N/A *styled boxes*. A styled box is composed of 9 rectangular (and potentially
2N/Aempty) regions, which are used to seamlessly draw the styled box on screen:
2N/A@multitable @columnfractions 0.3 0.3 0.3
2N/A@item Northwest (nw) @tab North (n) @tab Northeast (ne)
2N/A@item West (w) @tab Center (c) @tab East (e)
2N/A@item Southwest (sw) @tab South (s) @tab Southeast (se)
2N/ATo support any size of box on screen, the center slice and the slices for the
2N/Atop, bottom, and sides are all scaled to the correct size for the component on
2N/Ascreen, using the following rules:
2N/A@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.
2N/A@item The corner slices (northwest, northeast, southeast, and southwest) are not scaled.
2N/A@item The center slice is scaled to fill the remaining space in the middle.
2N/AAs an example of how an image might be sliced up, consider the styled box
2N/Aused for a terminal view.
2N/A@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.
2N/A@c @image{Box_slice_example_terminal,,,,.png}
2N/A@subsection Creating Styled Box Images
2N/AThe Inkscape_ scalable vector graphics editor is a very useful tool for
2N/Acreating styled box images. One process that works well for slicing a drawing
2N/Ainto the necessary image slices is:
2N/A@item Create or open the drawing you'd like use.
2N/A@item Create a new layer on the top of the layer stack. Make it visible. Select this layer as the current layer.
2N/A@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.
2N/A@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.
2N/A@item Save the drawing.
2N/A@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.
2N/A@item Click the layer hide icon for the slice layer in the layer palette. The rectangles will remain selected, even though they are hidden.
2N/A@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.
2N/A@section Theme File Manual
2N/AThe theme file is a plain text file. Lines that begin with ``#`` are ignored
2N/Aand considered comments. (Note: This may not be the case if the previous line
2N/Aended where a value was expected.)
2N/AThe theme file contains two types of statements:
2N/A@item Global properties.
2N/A@item Component construction.
2N/A@subsection Global Properties
2N/AGlobal properties are specified with the simple format:
2N/A@item name2: "value which may contain spaces"
2N/AIn this example, name3 is assigned a color value.
2N/A@subsection Global Property List
2N/A@multitable @columnfractions 0.3 0.6
2N/A@item title-text @tab Specifies the text to display at the top center of the screen as a title.
2N/A@item title-font @tab Defines the font used for the title message at the top of the screen.
2N/A@item title-color @tab Defines the color of the title message.
2N/A@item message-font @tab Defines the font used for messages, such as when GRUB is unable to automatically boot an entry.
2N/A@item message-color @tab Defines the color of the message text.
2N/A@item message-bg-color @tab Defines the background color of the message text area.
2N/A@item desktop-image @tab Specifies the image to use as the background. It will be scaled to fit the screen size.
2N/A@item desktop-color @tab Specifies the color for the background if *desktop-image* is not specified.
2N/A@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.
2N/A@subsection Component Construction
2N/AGreater customizability comes is provided by components. A tree of components
2N/Aforms the user interface. *Containers* are components that can contain other
2N/Acomponents, and there is always a single root component which is an instance
2N/Aof a *canvas* container.
2N/AComponents are created in the theme file by prefixing the type of component
2N/A@code{ + label @{ text="GRUB" font="aqui 11" color="#8FF" @} }
2N/Aproperties of a component are specified as "name = value" (whitespace
2N/Asurrounding tokens is optional and is ignored) where *value* may be:
2N/A@item a single word (
e.g., ``align = center``, ``color = #FF8080``),
2N/A@item a quoted string (
e.g., ``text = "Hello, World!"``), or
2N/A@item a tuple (
e.g., ``preferred_size = (120, 80)``).
2N/A@subsection Component List
2N/AThe following is a list of the components and the properties they support.
2N/A A label displays a line of text.
2N/A @multitable @columnfractions 0.2 0.7
2N/A @item text @tab The text to display.
2N/A @item font @tab The font to use for text display.
2N/A @item color @tab The color of the text.
2N/A @item align @tab The horizontal alignment of the text within the component. Options are ``left``, ``center``, and ``right``.
2N/A A component that displays an image. The image is scaled to fit the
2N/A component, although the preferred size defaults to the image's original
2N/A size unless the ``preferred_size`` property is explicitly set.
2N/A @multitable @columnfractions 0.2 0.7
2N/A @item file @tab The full path to the image file to load.
2N/A Displays a horizontally oriented progress bar. It can be rendered using
2N/A simple solid filled rectangles, or using a pair of pixmap styled boxes.
2N/A @multitable @columnfractions 0.2 0.7
2N/A @item fg_color @tab The foreground color for plain solid color rendering.
2N/A @item bg_color @tab The background color for plain solid color rendering.
2N/A @item border_color @tab The border color for plain solid color rendering.
2N/A @item text_color @tab The text color.
2N/A @item show_text @tab Boolean value indicating whether or not text should be displayed on the progress bar. If set to *false*, then no text will be displayed on the bar. If set to any other value, text will be displayed on the bar.
2N/A @item bar_style @tab The styled box specification for the frame of the progress bar. Example: ``progress_frame_*.png``
2N/A @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``.
2N/A @item text @tab The text to display on the progress bar. If the progress bar's ID is set to ``__timeout__``, then GRUB will updated this property with an informative message as the timeout approaches.
2N/A @item value @tab The progress bar current value. Normally not set manually.
2N/A @item start @tab The progress bar start value. Normally not set manually.
2N/A @item end @tab The progress bar end value. Normally not set manually.
2N/A@item circular_progress
2N/A Displays a circular progress indicator. The appearance of this component
2N/A is determined by two images: the *center* image and the *tick* image. The
2N/A center image is generally larger and will be drawn in the center of the
2N/A component. Around the circumference of a circle within the component, the
2N/A tick image will be drawn a certain number of times, depending on the
2N/A properties of the component.
2N/A @multitable @columnfractions 0.3 0.6
2N/A @tab The file name of the image to draw in the center of the component.
2N/A @tab The file name of the image to draw for the tick marks.
2N/A @tab The number of ticks that make up a full circle.
2N/A @item ticks_disappear
2N/A @tab Boolean value indicating whether tick marks should progressively appear,
2N/A or progressively disappear as *value* approaches *end*. Specify
2N/A ``true`` or ``false``.
2N/A @tab The progress indicator current value. Normally not set manually.
2N/A @tab The progress indicator start value. Normally not set manually.
2N/A @tab The progress indicator end value. Normally not set manually.
2N/A Displays the GRUB boot menu. It allows selecting items and executing them.
2N/A @multitable @columnfractions 0.4 0.5
2N/A @tab The font to use for the menu item titles.
2N/A @item selected_item_font
2N/A @tab The font to use for the selected menu item, or ``inherit`` (the default)
2N/A to use ``item_font`` for the selected menu item as well.
2N/A @tab The color to use for the menu item titles.
2N/A @item selected_item_color
2N/A @tab The color to use for the selected menu item, or ``inherit`` (the default)
2N/A to use ``item_color`` for the selected menu item as well.
2N/A @tab The width of menu item icons. Icons are scaled to the specified size.
2N/A @tab The height of menu item icons.
2N/A @tab The height of each menu item in pixels.
2N/A @tab The amount of space in pixels to leave on each side of the menu item
2N/A @item item_icon_space
2N/A @tab The space between an item's icon and the title text, in pixels.
2N/A @tab The amount of space to leave between menu items, in pixels.
2N/A @item menu_pixmap_style
2N/A @tab The image file pattern for the menu frame styled box.
2N/A Example: ``menu_*.png`` (this will use images such as ``
menu_c.png``,
2N/A @item selected_item_pixmap_style
2N/A @tab The image file pattern for the selected item highlight styled box.
2N/A @tab Boolean value indicating whether the scroll bar should be drawn if the
2N/A frame and thumb styled boxes are configured.
2N/A @item scrollbar_frame
2N/A @tab The image file pattern for the entire scroll bar.
2N/A Example: ``scrollbar_*.png``
2N/A @item scrollbar_thumb
2N/A @tab The image file pattern for the scroll bar thumb (the part of the scroll
2N/A bar that moves as scrolling occurs).
2N/A Example: ``scrollbar_thumb_*.png``
2N/A @item max_items_shown
2N/A @tab The maximum number of items to show on the menu. If there are more than
2N/A *max_items_shown* items in the menu, the list will scroll to make all
2N/A Canvas is a container that allows manual placement of components within it.
2N/A It does not alter the positions of its child components. It assigns all
2N/A child components their preferred sizes.
2N/A The *hbox* container lays out its children from left to right, giving each
2N/A one its preferred width. The height of each child is set to the maximum of
2N/A the preferred heights of all children.
2N/A The *vbox* container lays out its children from top to bottom, giving each
2N/A one its preferred height. The width of each child is set to the maximum of
2N/A the preferred widths of all children.
2N/A@subsection Common properties
2N/AThe following properties are supported by all components:
2N/A The distance from the left border of container to left border of the object in either of three formats:
2N/A @multitable @columnfractions 0.2 0.7
2N/A @item x @tab Value in pixels
2N/A @item p% @tab Percentage
2N/A @item p%+x @tab mixture of both
2N/A The distance from the left border of container to left border of the object in same format.
2N/A The width of object in same format.
2N/A The height of object in same format.
2N/A The identifier for the component. This can be any arbitrary string.
2N/A The ID can be used by scripts to refer to various components in the GUI
2N/A component tree. Currently, there is one special ID value that GRUB
2N/A @multitable @columnfractions 0.2 0.7
2N/A @item ``__timeout__`` @tab Any component with this ID will have its *text*, *start*, *end*, *value*, and *visible* properties set by GRUB when it is counting down to an automatic boot of the default menu entry.
2N/A@chapter Booting GRUB from the network
2N/AThe following instructions only work on PC BIOS systems where the Preboot
2N/AeXecution Environment (PXE) is available.
2N/ATo generate a PXE boot image, run:
2N/Ato the PXE (TFTP) server, ensuring that @file{*.mod} and @file{*.lst} are
2N/Aaccessible via the @file{
/boot/grub/} path from the TFTP server root. Set
2N/Athe DHCP server configuration to offer @file{
grub.pxe} as the boot file (the
2N/A@samp{filename} option in ISC dhcpd).
2N/AYou can also use the @command{grub-mknetdir} utility to generate an image
2N/Aand a GRUB directory tree, rather than copying files around manually.
2N/AAfter GRUB has started, files on the TFTP server will be accessible via the
2N/AThe server and gateway IP address can be controlled by changing the
2N/A@samp{(pxe)} device name to @samp{(pxe:@var{server-ip})} or
2N/A@samp{(pxe:@var{server-ip}:@var{gateway-ip})}. Note that this should be
2N/Achanged both in the prefix and in any references to the device name in the
2N/AGRUB provides several environment variables which may be used to inspect or
2N/Achange the behaviour of the PXE device:
2N/AThe IP address of this machine. Read-only.
2N/AThe network interface's MAC address. Read-only.
2N/A@item net_pxe_hostname
2N/AThe client host name provided by DHCP. Read-only.
2N/AThe client domain name provided by DHCP. Read-only.
2N/A@item net_pxe_rootpath
2N/AThe path to the client's root disk provided by DHCP. Read-only.
2N/A@item net_pxe_extensionspath
2N/AThe path to additional DHCP vendor extensions provided by DHCP. Read-only.
2N/A@item net_pxe_boot_file
2N/AThe boot file name provided by DHCP. Read-only.
2N/A@item net_pxe_dhcp_server_name
2N/AThe name of the DHCP server responsible for these boot parameters.
2N/AThe PXE transfer block size. Read-write, defaults to 512.
2N/A@item pxe_default_server
2N/AThe default PXE server. Read-write, although setting this is only useful
2N/Abefore opening a PXE device.
2N/A@item pxe_default_gateway
2N/AThe default gateway to use when contacting the PXE server. Read-write,
2N/Aalthough setting this is only useful before opening a PXE device.
2N/A@node Serial terminal
2N/A@chapter Using GRUB via a serial line
2N/AThis chapter describes how to use the serial terminal support in GRUB.
2N/Acould be very useful to control the computers through serial
2N/Acommunications. To connect one computer with another via a serial line,
2N/Ayou need to prepare a null-modem (cross) serial cable, and you may need
2N/Ato have multiport serial boards, if your computer doesn't have extra
2N/Aserial ports. In addition, a terminal emulator is also required, such as
2N/Aminicom. Refer to a manual of your operating system, for more
2N/AAs for GRUB, the instruction to set up a serial terminal is quite
2N/Asimple. Here is an example:
2N/Agrub> @kbd{serial --unit=0 --speed=9600}
2N/Agrub> @kbd{terminal_input serial; terminal_output serial}
2N/AThe command @command{serial} initializes the serial unit 0 with the
2N/Aspeed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
2N/Ayou want to use COM2, you must specify @samp{--unit=1} instead. This
2N/Acommand accepts many other options, so please refer to @ref{serial},
2N/AThe commands @command{terminal_input} (@pxref{terminal_input}) and
2N/A@command{terminal_output} (@pxref{terminal_output}) choose which type of
2N/Aterminal you want to use. In the case above, the terminal will be a
2N/Aserial terminal, but you can also pass @code{console} to the command,
2N/Aas @samp{terminal_input serial console}. In this case, a terminal in which
2N/Ayou press any key will be selected as a GRUB terminal. In the example above,
2N/Anote that you need to put both commands on the same command line, as you
2N/Awill lose the ability to type commands on the console after the first
2N/AHowever, note that GRUB assumes that your terminal emulator is
2N/Acompatible with VT100 by default. This is true for most terminal
2N/Aemulators nowadays, but you should pass the option @option{--dumb} to
2N/Athe command if your terminal emulator is not VT100-compatible or
2N/Aimplements few VT100 escape sequences. If you specify this option then
2N/AGRUB provides you with an alternative menu interface, because the normal
2N/Amenu requires several fancy features of your terminal.
2N/A@node Vendor power-on keys
2N/A@chapter Using GRUB with vendor power-on keys
2N/ASome laptop vendors provide an additional power-on button which boots another
2N/AOS. GRUB supports such buttons with the @samp{GRUB_TIMEOUT_BUTTON},
2N/A@samp{GRUB_DEFAULT_BUTTON}, @samp{GRUB_HIDDEN_TIMEOUT_BUTTON} and
2N/Aconfiguration}). @samp{GRUB_TIMEOUT_BUTTON}, @samp{GRUB_DEFAULT_BUTTON} and
2N/A@samp{GRUB_HIDDEN_TIMEOUT_BUTTON} are used instead of the corresponding
2N/Avariables without the @samp{_BUTTON} suffix when powered on using the special
2N/Abutton. @samp{GRUB_BUTTON_CMOS_ADDRESS} is vendor-specific and partially
2N/Amodel-specific. Values known to the GRUB team are:
2N/A@item Asus EeePC 1005PE
2N/ATo take full advantage of this function, install GRUB into the MBR
2N/A(@pxref{Installing GRUB using grub-install}).
2N/AIf you have a laptop which has a similar feature and not in the above list
2N/Acould you figure your address and contribute?
2N/ATo discover the address do the following:
2N/A@item boot using vendor button
2N/AThen compare these text files and find where a bit was toggled.
E.g. in
2N/Acase of Dell XPS it was:
2N/AIt's a bit number 3 as seen from following table:
2N/A@multitable @columnfractions .2 .2
2N/A0x47 is decimal 71. Linux nvram implementation cuts first 14 bytes of
2N/ACMOS. So the real byte address in CMOS is 71+14=85
2N/ASo complete address is 85:3
2N/A@chapter GRUB image files
2N/A@c FIXME: parts of this section are specific to PC BIOS right now.
2N/AGRUB consists of several images: a variety of bootstrap images for starting
2N/AGRUB in various ways, a kernel image, and a set of modules which are
2N/Acombined with the kernel image to form a core image. Here is a short
2N/AOn PC BIOS systems, this image is the first part of GRUB to start. It is
2N/Awritten to a master boot record (MBR) or to the boot sector of a partition.
2N/ABecause a PC boot sector is 512 bytes, the size of this image is exactly 512
2N/AThe sole function of @file{
boot.img} is to read the first sector of the core
2N/Aimage from a local disk and jump to it. Because of the size restriction,
2N/A@file{
boot.img} cannot understand any file system structure, so
2N/A@command{grub-setup} hardcodes the location of the first sector of the core
2N/AThis image is used as the first sector of the core image when booting from a
2N/Ahard disk. It reads the rest of the core image into memory and starts the
2N/Akernel. Since file system handling is not yet available, it encodes the
2N/Alocation of the core image using a block list format.
2N/AThis image is used as the first sector of the core image when booting from a
2N/AThis image is used as the start of the core image when booting from the
2N/Anetwork using PXE. @xref{Network}.
2N/AThis image may be placed at the start of the core image in order to make
2N/AGRUB look enough like a Linux kernel that it can be booted by LILO using an
2N/A@samp{image=} section.
2N/AThis image contains GRUB's basic run-time facilities: frameworks for device
2N/Aand file handling, environment variables, the rescue mode command-line
2N/Aparser, and so on. It is rarely used directly, but is built into all core
2N/AThis is the core image of GRUB. It is built dynamically from the kernel
2N/Aimage and an arbitrary list of modules by the @command{grub-mkimage}
2N/Aprogram. Usually, it contains enough modules to access @file{
/boot/grub},
2N/Aand loads everything else (including menu handling, the ability to load
2N/Atarget operating systems, and so on) from the file system at run-time. The
2N/Amodular design allows the core image to be kept small, since the areas of
2N/Adisk where it must be installed are often as small as 32KB.
2N/A@xref{BIOS installation}, for details on where the core image can be
2N/Ainstalled on PC systems.
2N/AEverything else in GRUB resides in dynamically loadable modules. These are
2N/Aoften loaded automatically, or built into the core image if they are
2N/Aessential, but may also be loaded manually using the @command{insmod}
2N/Acommand (@pxref{insmod}).
2N/A@heading For GRUB Legacy users
2N/AGRUB 2 has a different design from GRUB Legacy, and so correspondences with
2N/Athe images it used cannot be exact. Nevertheless, GRUB Legacy users often
2N/Aask questions in the terms they are familiar with, and so here is a brief
2N/Aguide to how GRUB 2's images relate to that.
2N/AStage 1 from GRUB Legacy was very similar to @file{
boot.img} in GRUB 2, and
2N/Athey serve the same function.
2N/AIn GRUB Legacy, Stage 1.5's function was to include enough filesystem code
2N/Ato allow the much larger Stage 2 to be read from an ordinary filesystem. In
2N/Athis respect, its function was similar to @file{
core.img} in GRUB 2.
2N/AHowever, @file{
core.img} is much more capable than Stage 1.5 was; since it
2N/Aoffers a rescue shell, it is sometimes possible to recover manually in the
2N/Aevent that it is unable to load any other modules, for example if partition
2N/Anumbers have changed. @file{
core.img} is built in a more flexible way,
2N/Aallowing GRUB 2 to support reading modules from advanced disk types such as
2N/AGRUB Legacy could run with only Stage 1 and Stage 2 in some limited
2N/Aconfigurations, while GRUB 2 requires @file{
core.img} and cannot work
2N/AGRUB 2 has no single Stage 2 image. Instead, it loads modules from
2N/A@item stage2_eltorito
2N/AIn GRUB 2, images for booting from CD-ROM drives are now constructed using
2N/Acontains the @samp{iso9660} module. It is usually best to use the
2N/A@command{grub-mkrescue} program for this.
2N/AThere is as yet no equivalent for @file{nbgrub} in GRUB 2; it was used by
2N/AEtherboot and some other network boot loaders.
2N/AIn GRUB 2, images for PXE network booting are now constructed using
2N/Acontains the @samp{pxe} and @samp{pxecmd} modules. @xref{Network}.
2N/A@chapter Filesystem syntax and semantics
2N/AGRUB uses a special syntax for specifying disk drives which can be
2N/Aaccessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
2N/Abetween IDE, ESDI, SCSI, or others. You must know yourself which BIOS
2N/Adevice is equivalent to which OS device. Normally, that will be clear if
2N/Ayou see the files in a device or use the command @command{search}
2N/A* Device syntax:: How to specify devices
2N/A* File name syntax:: How to specify files
2N/A* Block list syntax:: How to specify block lists
2N/A@section How to specify devices
2N/AThe device syntax is like this:
2N/A@code{(@var{device}[,@var{partmap-name1}@var{part-num1}[,@var{partmap-name2}@var{part-num2}[,...]]])}
2N/A@samp{[]} means the parameter is optional. @var{device} depends on the disk
2N/Adriver in use. BIOS and EFI disks use either @samp{fd} or @samp{hd} followed
2N/Aby a digit, like @samp{fd0}, or @samp{cd}.
2N/AAHCI, PATA (ata), crypto, USB use the name of driver followed by a number.
2N/AMemdisk and host are limited to one disk and so it's refered just by driver
2N/ARAID (md), ofdisk (ieee1275), LVM (lv) and arcdisk (arc) use intrinsic name
2N/Aof disk prefixed by driver name. Conflicts are solved by suffixing a number
2N/Aif necessarry. Commas need to be escaped.
2N/ALoopback uses whatever name specified to @command{loopback} command.
2N/AHostdisk uses names specified in
device.map or hostdisk/<OS NAME>.
2N/AFor crypto and RAID (md) additionally you can use the syntax
2N/A<driver name>uuid/<uuid>.
2N/A(cryptouuid/123456789abcdef0123456789abcdef0)
2N/A(mduuid/123456789abcdef0123456789abcdef0)
2N/A@var{part-num} represents the partition number of @var{device}, starting
2N/Afrom one. @var{partname} is optional but is recommended since disk may have
2N/Aseveral top-level partmaps. Specifying third and later component you can access
2N/AThe syntax @samp{(hd0)} represents using the entire disk (or the
2N/AMBR when installing GRUB), while the syntax @samp{(hd0,1)}
2N/Arepresents using the first partition of the disk (or the boot sector
2N/Aof the partition when installing GRUB).
2N/AIf you enabled the network support, the special drives @samp{(tftp)},
2N/A@samp{(http)} and so on ars also available.
2N/ABefore using the network drive, you must initialize the network.
2N/A@xref{Network}, for more information.
2N/AIf you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
2N/Aa GRUB bootable CD-ROM}, for details.
2N/A@node File name syntax
2N/A@section How to specify files
2N/AThere are two ways to specify files, by @dfn{absolute file name} and by
2N/AAn absolute file name resembles a Unix absolute file name, using
2N/A@samp{/} for the directory separator (not @samp{\} as in DOS). One
2N/Adisk. If you omit the device name in an absolute file name, GRUB uses
2N/AGRUB's @dfn{root device} implicitly. So if you set the root device to,
2N/Asay, @samp{(hd1,1)} by the command @samp{set root=(hd1,1)} (@pxref{set}),
2N/A@node Block list syntax
2N/A@section How to specify block lists
2N/AA block list is used for specifying a file that doesn't appear in the
2N/Afilesystem, like a chainloader. The syntax is
2N/A@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
2N/A@code{0+100,200+1,300+300}
2N/AThis represents that GRUB should read blocks 0 through 99, block 200,
2N/Aand blocks 300 through 599. If you omit an offset, then GRUB assumes
2N/ALike the file name syntax (@pxref{File name syntax}), if a blocklist
2N/Adoes not contain a device name, then GRUB uses GRUB's @dfn{root
2N/Adevice}. So @code{(hd0,2)+1} is the same as @code{+1} when the root
2N/Adevice is @samp{(hd0,2)}.
2N/A@chapter GRUB's user interface
2N/AGRUB has both a simple menu interface for choosing preset entries from a
2N/Aconfiguration file, and a highly flexible command-line for performing
2N/Aany desired combination of boot commands.
2N/AGRUB looks for its configuration file as soon as it is loaded. If one
2N/Ais found, then the full menu interface is activated using whatever
2N/Aentries were found in the file. If you choose the @dfn{command-line} menu
2N/Aoption, or if the configuration file was not found, then GRUB drops to
2N/Athe command-line interface.
2N/A* Command-line interface:: The flexible command-line interface
2N/A* Menu interface:: The simple menu interface
2N/A* Menu entry editor:: Editing a menu entry
2N/A@node Command-line interface
2N/A@section The flexible command-line interface
2N/AThe command-line interface provides a prompt and after it an editable
2N/Atext area much like a command-line in Unix or DOS. Each command is
2N/Aimmediately executed after it is entered@footnote{However, this
2N/Abehavior will be changed in the future version, in a user-invisible
2N/Away.}. The commands (@pxref{Command-line and menu entry commands}) are a
2N/Asubset of those available in the configuration file, used with exactly
2N/ACursor movement and editing of the text on the line can be done via a
2N/Asubset of the functions available in the Bash shell:
2N/AMove forward one character.
2N/AMove back one character.
2N/AMove to the start of the line.
2N/AMove the the end of the line.
2N/ADelete the character underneath the cursor.
2N/ADelete the character to the left of the cursor.
2N/AKill the text from the current cursor position to the end of the line.
2N/AKill backward from the cursor to the beginning of the line.
2N/AYank the killed text back into the buffer at the cursor.
2N/AMove up through the history list.
2N/AMove down through the history list.
2N/AWhen typing commands interactively, if the cursor is within or before
2N/Athe first word in the command-line, pressing the @key{TAB} key (or
2N/A@key{C-i}) will display a listing of the available commands, and if the
2N/Acursor is after the first word, the @kbd{@key{TAB}} will provide a
2N/Acompletion listing of disks, partitions, and file names depending on the
2N/Acontext. Note that to obtain a list of drives, one must open a
2N/Aparenthesis, as @command{root (}.
2N/ANote that you cannot use the completion functionality in the TFTP
2N/Afilesystem. This is because TFTP doesn't support file name listing for
2N/A@section The simple menu interface
2N/AThe menu interface is quite easy to use. Its commands are both
2N/Areasonably intuitive and described on screen.
2N/ABasically, the menu interface provides a list of @dfn{boot entries} to
2N/Athe user to choose from. Use the arrow keys to select the entry of
2N/Achoice, then press @key{RET} to run it. An optional timeout is
2N/Aavailable to boot the default entry (the first one if not set), which is
2N/Aaborted by pressing any key.
2N/ACommands are available to enter a bare command-line by pressing @key{c}
2N/A(which operates exactly like the non-config-file version of GRUB, but
2N/Aallows one to return to the menu if desired by pressing @key{ESC}) or to
2N/Aedit any of the @dfn{boot entries} by pressing @key{e}.
2N/AIf you protect the menu interface with a password (@pxref{Security}),
2N/Aall you can do is choose an entry by pressing @key{RET}, or press
2N/A@key{p} to enter the password.
2N/A@node Menu entry editor
2N/A@section Editing a menu entry
2N/AThe menu entry editor looks much like the main menu interface, but the
2N/Alines in the menu are individual commands in the selected entry instead
2N/AIf an @key{ESC} is pressed in the editor, it aborts all the changes made
2N/Ato the configuration entry and returns to the main menu interface.
2N/AEach line in the menu entry can be edited freely, and you can add new lines
2N/Aby pressing @key{RET} at the end of a line. To boot the edited entry, press
2N/AAlthough GRUB unfortunately does not support @dfn{undo}, you can do almost
2N/Athe same thing by just returning to the main menu using @key{ESC}.
2N/A@chapter GRUB environment variables
2N/AGRUB supports environment variables which are rather like those offered by
2N/Aall Unix-like systems. Environment variables have a name, which is unique
2N/Aand is usually a short identifier, and a value, which is an arbitrary string
2N/Aof characters. They may be set (@pxref{set}), unset (@pxref{unset}), or
2N/Alooked up (@pxref{Shell-like scripting}) by name.
2N/AA number of environment variables have special meanings to various parts of
2N/AGRUB. Others may be used freely in GRUB configuration files.
2N/A* Special environment variables::
2N/A* Environment block::
2N/A@node Special environment variables
2N/A@section Special environment variables
2N/AThese variables have special meaning to GRUB.
2N/A* menu_color_highlight::
2N/A* menu_color_normal::
2N/A* net_pxe_boot_file::
2N/A* net_pxe_dhcp_server_name::
2N/A* net_pxe_extensionspath::
2N/A* pxe_default_gateway::
2N/A* pxe_default_server::
2N/AWhen chain-loading another boot loader (@pxref{Chain-loading}), GRUB may
2N/Aneed to know what BIOS drive number corresponds to the root device
2N/A(@pxref{root}) so that it can set up registers properly. If the
2N/A@var{biosnum} variable is set, it overrides GRUB's own means of guessing
2N/AFor an alternative approach which also changes BIOS drive mappings for the
2N/Achain-loaded system, @pxref{drivemap}.
2N/AWhen executing a menu entry, GRUB sets the @var{chosen} variable to the
2N/Atitle of the entry being executed.
2N/AIf the menu entry is in one or more submenus, then @var{chosen} is set to
2N/Athe titles of each of the submenus starting from the top level followed by
2N/Athe title of the menu entry itself, separated by @samp{>}.
2N/A@node color_highlight
2N/A@subsection color_highlight
2N/AThis variable contains the ``highlight'' foreground and background terminal
2N/Acolors, separated by a slash (@samp{/}). Setting this variable changes
2N/Athose colors. For the available color names, @pxref{color_normal}.
2N/A@subsection color_normal
2N/AThis variable contains the ``normal'' foreground and background terminal
2N/Acolors, separated by a slash (@samp{/}). Setting this variable changes
2N/Athose colors. Each color must be a name from the following list:
2N/AThis variable may be set to enable debugging output from various components
2N/Aof GRUB. The value is a list of debug facility names separated by
2N/Awhitespace or @samp{,}, or @samp{all} to enable all available debugging
2N/AIf this variable is set, it identifies a menu entry that should be selected
2N/Aby default, possibly after a timeout (@pxref{timeout}). The entry may be
2N/Aidentified by number or by title.
2N/AIf the entry is in a submenu, then it must be identified using the titles of
2N/Aeach of the submenus starting from the top level followed by the number or
2N/Atitle of the menu entry itself, separated by @samp{>}. For example, take
2N/Athe following menu structure:
2N/A``Menu Entry 3'' would then be identified as
2N/A@samp{Submenu 2>Submenu 3>Menu Entry 3}.
2N/AThis variable is often set by @samp{GRUB_DEFAULT} (@pxref{Simple
2N/Aconfiguration}), @command{grub-set-default}, or @command{grub-reboot}.
2N/AIf this variable is set, it identifies a menu entry that should be selected
2N/Aif the default menu entry fails to boot. Entries are identified in the same
2N/Away as for @samp{default} (@pxref{default}).
2N/AIf this variable is set, it sets the resolution used on the @samp{gfxterm}
2N/Agraphical terminal. Note that you can only use modes which your graphics
2N/Acard supports via VESA BIOS Extensions (VBE), so for example native LCD
2N/Apanel resolutions may not be available. The default is @samp{auto}, which
2N/Aselects a platform-specific default that should look reasonable.
2N/AThe resolution may be specified as a sequence of one or more modes,
2N/Aseparated by commas (@samp{,}) or semicolons (@samp{;}); each will be tried
2N/Ain turn until one is found. Each mode should be either @samp{auto},
2N/A@samp{@var{width}x@var{height}}, or
2N/A@samp{@var{width}x@var{height}x@var{depth}}.
2N/A@subsection gfxpayload
2N/AIf this variable is set, it controls the video mode in which the Linux
2N/Akernel starts up, replacing the @samp{vga=} boot option (@pxref{linux}). It
2N/Amay be set to @samp{text} to force the Linux kernel to boot in normal text
2N/Amode, @samp{keep} to preserve the graphics mode set using @samp{gfxmode}, or
2N/Aany of the permitted values for @samp{gfxmode} to set a particular graphics
2N/Amode (@pxref{gfxmode}).
2N/ADepending on your kernel, your distribution, your graphics card, and the
2N/Aphase of the moon, note that using this option may cause
GNU/Linux to suffer
2N/Afrom various display problems, particularly during the early part of the
2N/Aboot sequence. If you have problems, set this variable to @samp{text} and
2N/AGRUB will tell Linux to boot in normal text mode.
2N/AThe default is platform-specific. On platforms with a native text mode
2N/A(such as PC BIOS platforms), the default is @samp{text}. Otherwise the
2N/Adefault may be @samp{auto} or a specific video mode.
2N/AThis variable is often set by @samp{GRUB_GFXPAYLOAD_LINUX} (@pxref{Simple
2N/A@subsection gfxterm_font
2N/AIf this variable is set, it names a font to use for text on the
2N/A@samp{gfxterm} graphical terminal. Otherwise, @samp{gfxterm} may use any
2N/AIf this variable is set, it names a directory in which the GRUB graphical
2N/Amenu should look for icons after looking in the theme's @samp{icons}
2N/Adirectory. @xref{Theme file format}.
2N/AIf this variable is set, it names the language code that the
2N/A@command{gettext} command (@pxref{gettext}) uses to translate strings. For
2N/Aexample, French would be named as @samp{fr}, and Simplified Chinese as
2N/A@command{grub-mkconfig} (@pxref{Simple configuration}) will try to set a
2N/Areasonable default for this variable based on the system locale.
2N/A@subsection locale_dir
2N/AIf this variable is set, it names the directory where translation files may
2N/Ainternationalization is disabled.
2N/A@command{grub-mkconfig} (@pxref{Simple configuration}) will set a reasonable
2N/Adefault for this variable if internationalization is needed and any
2N/Atranslation files are available.
2N/A@node menu_color_highlight
2N/A@subsection menu_color_highlight
2N/AThis variable contains the foreground and background colors to be used for
2N/Athe highlighted menu entry, separated by a slash (@samp{/}). Setting this
2N/Avariable changes those colors. For the available color names,
2N/A@pxref{color_normal}.
2N/AThe default is the value of @samp{color_highlight}
2N/A(@pxref{color_highlight}).
2N/A@node menu_color_normal
2N/A@subsection menu_color_normal
2N/AThis variable contains the foreground and background colors to be used for
2N/Anon-highlighted menu entries, separated by a slash (@samp{/}). Setting this
2N/Avariable changes those colors. For the available color names,
2N/A@pxref{color_normal}.
2N/AThe default is the value of @samp{color_normal} (@pxref{color_normal}).
2N/A@node net_pxe_boot_file
2N/A@subsection net_pxe_boot_file
2N/A@node net_pxe_dhcp_server_name
2N/A@subsection net_pxe_dhcp_server_name
2N/A@subsection net_pxe_domain
2N/A@node net_pxe_extensionspath
2N/A@subsection net_pxe_extensionspath
2N/A@node net_pxe_hostname
2N/A@subsection net_pxe_hostname
2N/A@subsection net_pxe_ip
2N/A@subsection net_pxe_mac
2N/A@node net_pxe_rootpath
2N/A@subsection net_pxe_rootpath
2N/AIf set to @samp{1}, pause output after each screenful and wait for keyboard
2N/Ainput. The default is not to pause output.
2N/AThe location of the @samp{
/boot/grub} directory as an absolute file name
2N/A(@pxref{File name syntax}). This is normally set by GRUB at startup based
2N/Aon information provided by @command{grub-install}. GRUB modules are
2N/Adynamically loaded from this directory, so it must be set correctly in order
2N/Afor many parts of GRUB to work.
2N/A@subsection pxe_blksize
2N/A@node pxe_default_gateway
2N/A@subsection pxe_default_gateway
2N/A@node pxe_default_server
2N/A@subsection pxe_default_server
2N/AThe root device name (@pxref{Device syntax}). Any file names that do not
2N/Aspecify an explicit device name are read from this device. The default is
2N/Anormally set by GRUB at startup based on the value of @samp{prefix}
2N/AFor example, if GRUB was installed to the first partition of the first hard
2N/Adisk, then @samp{prefix} might be set to @samp{(hd0,msdos1)
/boot/grub} and
2N/A@samp{root} to @samp{hd0,msdos1}.
2N/A@subsection superusers
2N/AThis variable may be set to a list of superuser names to enable
2N/Aauthentication support. @xref{Security}.
2N/AThis variable may be set to a directory containing a GRUB graphical menu
2N/Atheme. @xref{Theme file format}.
2N/AThis variable is often set by @samp{GRUB_THEME} (@pxref{Simple
2N/AIf this variable is set, it specifies the time in seconds to wait for
2N/Akeyboard input before booting the default menu entry. A timeout of @samp{0}
2N/Ameans to boot the default entry immediately without displaying the menu; a
2N/Atimeout of @samp{-1} (or unset) means to wait indefinitely.
2N/AThis variable is often set by @samp{GRUB_TIMEOUT} or
2N/A@samp{GRUB_HIDDEN_TIMEOUT} (@pxref{Simple configuration}).
2N/A@node Environment block
2N/A@section The GRUB environment block
2N/AIt is often useful to be able to remember a small amount of information from
2N/Aone boot to the next. For example, you might want to set the default menu
2N/Aentry based on what was selected the last time. GRUB deliberately does not
2N/Aimplement support for writing files in order to minimise the possibility of
2N/Athe boot loader being responsible for file system corruption, so a GRUB
2N/Aconfiguration file cannot just create a file in the ordinary way. However,
2N/AGRUB provides an ``environment block'' which can be used to save a small
2N/AThe environment block is a preallocated 1024-byte file, which normally lives
2N/Atime, the @command{load_env} command (@pxref{load_env}) loads environment
2N/Avariables from it, and the @command{save_env} (@pxref{save_env}) command
2N/Asaves environment variables to it. From a running system, the
2N/A@command{grub-editenv} utility can be used to edit the environment block.
2N/AFor safety reasons, this storage is only available when installed on a plain
2N/Adisk (no LVM or RAID), using a non-checksumming filesystem (no ZFS), and
2N/Ausing BIOS or EFI functions (no ATA, USB or IEEE1275).
2N/A@command{grub-mkconfig} uses this facility to implement
2N/A@samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}).
2N/A@chapter The list of available commands
2N/AIn this chapter, we list all commands that are available in GRUB.
2N/ACommands belong to different groups. A few can only be used in
2N/Athe global section of the configuration file (or ``menu''); most
2N/Aof them can be entered on the command-line and can be used either
2N/Aanywhere in the menu or specifically in the menu entries.
2N/AIn rescue mode, only the @command{insmod} (@pxref{insmod}), @command{ls}
2N/A(@pxref{ls}), @command{set} (@pxref{set}), and @command{unset}
2N/A(@pxref{unset}) commands are normally available. If you end up in rescue
2N/Amode and do not know what to do, then @pxref{GRUB only offers a rescue
2N/A* Menu-specific commands::
2N/A* Command-line and menu entry commands::
2N/A@node Menu-specific commands
2N/A@section The list of commands for the menu only
2N/AThe semantics used in parsing the configuration file are the following:
2N/AThe files @emph{must} be in plain-text format.
2N/A@samp{#} at the beginning of a line in a configuration file means it is
2N/AOptions are separated by spaces.
2N/AAll numbers can be either decimal or hexadecimal. A hexadecimal number
2N/Amust be preceded by @samp{0x}, and is case-insensitive.
2N/AThese commands can only be used in the menu:
2N/A* menuentry:: Start a menu entry
2N/A* submenu:: Group menu entries
2N/A@subsection menuentry
2N/A@deffn Command menuentry @var{title} @
2N/A [@option{--class=class} @dots{}] [@option{--users=users}] @
2N/A [@option{--hotkey=key}] @
2N/A @{ @var{command}; @dots{} @}
2N/AThis defines a GRUB menu entry named @var{title}. When this entry is
2N/Aselected from the menu, GRUB will set the @var{chosen} environment variable
2N/Ato @var{title}, execute the list of commands given within braces, and if the
2N/Alast command in the list returned successfully and a kernel was loaded it
2N/Awill execute the @command{boot} command.
2N/AThe @option{--class} option may be used any number of times to group menu
2N/Aentries into classes. Menu themes may display different classes using
2N/AThe @option{--users} option grants specific users access to specific menu
2N/Aentries. @xref{Security}.
2N/AThe @option{--hotkey} option associates a hotkey with a menu entry.
2N/A@var{key} may be a single letter, or one of the aliases @samp{backspace},
2N/A@samp{tab}, or @samp{delete}.
2N/A@deffn Command submenu @var{title} @
2N/A [@option{--class=class} @dots{}] [@option{--users=users}] @
2N/A [@option{--hotkey=key}] @
2N/A @{ @var{menu entries} @dots{} @}
2N/AThis defines a submenu. An entry called @var{title} will be added to the
2N/Amenu; when that entry is selected, a new menu will be displayed showing all
2N/Athe entries within this submenu.
2N/AAll options are the same as in the @command{menuentry} command
2N/A@node General commands
2N/A@section The list of general commands
2N/ACommands usable anywhere in the menu and in the command-line.
2N/A* serial:: Set up a serial device
2N/A* terminal_input:: Manage input terminals
2N/A* terminal_output:: Manage output terminals
2N/A* terminfo:: Define terminal type
2N/A@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}]
2N/AInitialize a serial device. @var{unit} is a number in the range 0-3
2N/Aspecifying which serial port to use; default is 0, which corresponds to
2N/Athe port often called COM1. @var{port} is the I/O port where the UART
2N/Ais to be found; if specified it takes precedence over @var{unit}.
2N/A@var{speed} is the transmission speed; default is 9600. @var{word} and
2N/A@var{stop} are the number of data bits and stop bits. Data bits must
2N/Abe in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
2N/Abits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
2N/A@samp{even} and defaults to @samp{no}.
2N/AThe serial port is not used as a communication channel unless the
2N/A@command{terminal_input} or @command{terminal_output} command is used
2N/A(@pxref{terminal_input}, @pxref{terminal_output}).
2N/ASee also @ref{Serial terminal}.
2N/A@subsection terminal_input
2N/A@deffn Command terminal_input [@option{--append}|@option{--remove}] @
2N/A [terminal1] [terminal2] @dots{}
2N/AList or select an input terminal.
2N/AWith no arguments, list the active and available input terminals.
2N/AWith @option{--append}, add the named terminals to the list of active input
2N/Aterminals; any of these may be used to provide input to GRUB.
2N/AWith @option{--remove}, remove the named terminals from the active list.
2N/AWith no options but a list of terminal names, make only the listed terminal
2N/A@node terminal_output
2N/A@subsection terminal_output
2N/A@deffn Command terminal_output [@option{--append}|@option{--remove}] @
2N/A [terminal1] [terminal2] @dots{}
2N/AList or select an output terminal.
2N/AWith no arguments, list the active and available output terminals.
2N/AWith @option{--append}, add the named terminals to the list of active output
2N/Aterminals; all of these will receive output from GRUB.
2N/AWith @option{--remove}, remove the named terminals from the active list.
2N/AWith no options but a list of terminal names, make only the listed terminal
2N/A@deffn Command terminfo [-a|-u|-v] [term]
2N/ADefine the capabilities of your terminal by giving the name of an entry in
2N/Athe terminfo database, which should correspond roughly to a @samp{TERM}
2N/Aenvironment variable in Unix.
2N/AThe currently available terminal types are @samp{vt100}, @samp{vt100-color},
2N/A@samp{ieee1275}, and @samp{dumb}. If you need other terminal types, please
2N/Acontact us to discuss the best way to include support for these in GRUB.
2N/AThe @option{-a} (@option{--ascii}), @option{-u} (@option{--utf8}), and
2N/A@option{-v} (@option{--visual-utf8}) options control how non-ASCII text is
2N/Adisplayed. @option{-a} specifies an ASCII-only terminal; @option{-u}
2N/Aspecifies logically-ordered UTF-8; and @option{-v} specifies
2N/A"visually-ordered UTF-8" (in other words, arranged such that a terminal
2N/Aemulator without bidirectional text support will display right-to-left text
2N/Ain the proper order; this is not really proper UTF-8, but a workaround).
2N/AIf no option or terminal type is specified, the current terminal type is
2N/A@node Command-line and menu entry commands
2N/A@section The list of command-line and menu entry commands
2N/AThese commands are usable in the command-line and in menu entries. If
2N/Ayou forget a command, you can run the command @command{help}
2N/A* acpi:: Load ACPI tables
2N/A* badram:: Filter out bad regions of RAM
2N/A* blocklist:: Print a block list
2N/A* boot:: Start up your operating system
2N/A* cat:: Show the contents of a file
2N/A* chainloader:: Chain-load another boot loader
2N/A* cmp:: Compare two files
2N/A* configfile:: Load a configuration file
2N/A* cpuid:: Check for CPU features
2N/A* crc:: Calculate CRC32 checksums
2N/A* date:: Display or set current date and time
2N/A* drivemap:: Map a drive to another
2N/A* echo:: Display a line of text
2N/A* export:: Export an environment variable
2N/A* false:: Do nothing, unsuccessfully
2N/A* gettext:: Translate a string
2N/A* gptsync:: Fill an MBR based on GPT entries
2N/A* halt:: Shut down your computer
2N/A* help:: Show help messages
2N/A* initrd:: Load a Linux initrd
2N/A* initrd16:: Load a Linux initrd (16-bit mode)
2N/A* insmod:: Insert a module
2N/A* keystatus:: Check key modifier status
2N/A* linux:: Load a Linux kernel
2N/A* linux16:: Load a Linux kernel (16-bit mode)
2N/A* list_env:: List variables in environment block
2N/A* load_env:: Load variables from environment block
2N/A* loopback:: Make a device from a filesystem image
2N/A* ls:: List devices or files
2N/A* normal:: Enter normal mode
2N/A* normal_exit:: Exit from normal mode
2N/A* parttool:: Modify partition table entries
2N/A* password:: Set a clear-text password
2N/A* password_pbkdf2:: Set a hashed password
2N/A* pxe_unload:: Unload the PXE environment
2N/A* read:: Read user input
2N/A* reboot:: Reboot your computer
2N/A* save_env:: Save variables to environment block
2N/A* search:: Search devices by file, label, or UUID
2N/A* sendkey:: Emulate keystrokes
2N/A* set:: Set an environment variable
2N/A* true:: Do nothing, successfully
2N/A* unset:: Unset an environment variable
2N/A* uppermem:: Set the upper memory size
2N/A@deffn Command acpi [@option{-1}|@option{-2}] @
2N/A [@option{--exclude=table1,@dots{}}|@option{--load-only=table1,@dots{}}] @
2N/A [@option{--oemid=id}] [@option{--oemtable=table}] @
2N/A [@option{--oemtablerev=rev}] [@option{--oemtablecreator=creator}] @
2N/A [@option{--oemtablecreatorrev=rev}] [@option{--no-ebda}] @
2N/AModern BIOS systems normally implement the Advanced Configuration and Power
2N/AInterface (ACPI), and define various tables that describe the interface
2N/Abetween an ACPI-compliant operating system and the firmware. In some cases,
2N/Athe tables provided by default only work well with certain operating
2N/Asystems, and it may be necessary to replace some of them.
2N/ANormally, this command will replace the Root System Description Pointer
2N/A(RSDP) in the Extended BIOS Data Area to point to the new tables. If the
2N/A@option{--no-ebda} option is used, the new tables will be known only to
2N/AGRUB, but may be used by GRUB's EFI emulation.
2N/A@deffn Command badram addr,mask[,addr,mask...]
2N/AThis command notifies the memory manager that specified regions of
2N/ARAM ought to be filtered out (usually, because they're damaged). This
2N/Aremains in effect after a payload kernel has been loaded by GRUB, as
2N/Along as the loaded kernel obtains its memory map from GRUB. Kernels that
2N/Asupport this include Linux, GNU Mach, the kernel of FreeBSD and Multiboot
2N/Aaddress and a base address / mask pair, if all the bits of the page-aligned
2N/Aaddress that are enabled by the mask match with the base address, it means
2N/Athis page is to be filtered. This syntax makes it easy to represent patterns
2N/Athat are often result of memory damage, due to physical distribution of memory
2N/A@subsection blocklist
2N/A@deffn Command blocklist file
2N/APrint a block list (@pxref{Block list syntax}) for @var{file}.
2N/ABoot the OS or chain-loader which has been loaded. Only necessary if
2N/Arunning the fully interactive command-line (it is implicit at the end of
2N/A@deffn Command cat [@option{--dos}] file
2N/ADisplay the contents of the file @var{file}. This command may be useful
2N/Ato remind you of your OS's root partition:
2N/AIf the @option{--dos} option is used, then carriage return / new line pairs
2N/Awill be displayed as a simple new line. Otherwise, the carriage return will
2N/Abe displayed as a control character (@samp{<d>}) to make it easier to see
2N/Awhen boot problems are caused by a file formatted using DOS-style line
2N/A@subsection chainloader
2N/A@deffn Command chainloader [@option{--force}] file
2N/ALoad @var{file} as a chain-loader. Like any other file loaded by the
2N/Afilesystem code, it can use the blocklist notation (@pxref{Block list
2N/Asyntax}) to grab the first sector of the current partition with @samp{+1}.
2N/AIf you specify the option @option{--force}, then load @var{file} forcibly,
2N/Awhether it has a correct signature or not. This is required when you want to
2N/Aload a defective boot loader, such as SCO UnixWare 7.1.
2N/A@deffn Command cmp file1 file2
2N/ACompare the file @var{file1} with the file @var{file2}. If they differ
2N/Ain size, print the sizes like this:
2N/ADiffer in size: 0x1234 [foo], 0x4321 [bar]
2N/AIf the sizes are equal but the bytes at an offset differ, then print the
2N/ADiffer at the offset 777: 0xbe [foo], 0xef [bar]
2N/AIf they are completely identical, nothing will be printed.
2N/A@subsection configfile
2N/A@deffn Command configfile file
2N/ALoad @var{file} as a configuration file. If @var{file} defines any menu
2N/Aentries, then show a menu containing them immediately.
2N/A@deffn Command cpuid [-l]
2N/ACheck for CPU features. This command is only available on x86 systems.
2N/AWith the @option{-l} option, return true if the CPU supports long mode
2N/AIf invoked without options, this command currently behaves as if it had been
2N/Ainvoked with @option{-l}. This may change in the future.
2N/A@deffn Command crc file
2N/ADisplay the CRC32 checksum of @var{file}.
2N/A@deffn Command date [[year-]month-day] [hour:minute[:second]]
2N/AWith no arguments, print the current date and time.
2N/AOtherwise, take the current date and time, change any elements specified as
2N/Aarguments, and set the result as the new date and time. For example, `date
2N/A01-01' will set the current month and day to January 1, but leave the year,
2N/Ahour, minute, and second unchanged.
2N/A@deffn Command drivemap @option{-l}|@option{-r}|[@option{-s}] @
2N/AWithout options, map the drive @var{from_drive} to the drive @var{to_drive}.
2N/AThis is necessary when you chain-load some operating systems, such as DOS,
2N/Aif such an OS resides at a non-first drive. For convenience, any partition
2N/Asuffix on the drive is ignored, so you can safely use @verb{'${root}'} as a
2N/AWith the @option{-s} option, perform the reverse mapping as well, swapping
2N/AWith the @option{-l} option, list the current mappings.
2N/AWith the @option{-r} option, reset all mappings to the default values.
2N/Adrivemap -s (hd0) (hd1)
2N/A@deffn Command echo [@option{-n}] [@option{-e}] string @dots{}
2N/ADisplay the requested text and, unless the @option{-n} option is used, a
2N/Atrailing new line. If there is more than one string, they are separated by
2N/Aspaces in the output. As usual in GRUB commands, variables may be
2N/Asubstituted using @samp{$@{var@}}.
2N/AThe @option{-e} option enables interpretation of backslash escapes. The
2N/Afollowing sequences are recognised:
2N/Asuppress trailing new line
2N/AWhen interpreting backslash escapes, backslash followed by any other
2N/Acharacter will print that character.
2N/A@deffn Command export envvar
2N/AExport the environment variable @var{envvar}. Exported variables are visible
2N/Ato subsidiary configuration files loaded using @command{configfile}.
2N/ADo nothing, unsuccessfully. This is mainly useful in control constructs
2N/Asuch as @code{if} and @code{while} (@pxref{Shell-like scripting}).
2N/A@deffn Command gettext string
2N/ATranslate @var{string} into the current language.
2N/AThe current language code is stored in the @samp{lang} variable in GRUB's
2N/Aenvironment (@pxref{lang}). Translation files in MO format are read from
2N/A@deffn Command gptsync device [partition[+/-[type]]] @dots{}
2N/ADisks using the GUID Partition Table (GPT) also have a legacy Master Boot
2N/ARecord (MBR) partition table for compatibility with the BIOS and with older
2N/Aoperating systems. The legacy MBR can only represent a limited subset of
2N/AGPT partition entries.
2N/AThis command populates the legacy MBR with the specified @var{partition}
2N/Aentries on @var{device}. Up to three partitions may be used.
2N/A@var{type} is an MBR partition type code; prefix with @samp{0x} if you want
2N/Ato enter this in hexadecimal. The separator between @var{partition} and
2N/A@var{type} may be @samp{+} to make the partition active, or @samp{-} to make
2N/Ait inactive; only one partition may be active. If both the separator and
2N/Atype are omitted, then the partition will be inactive.
2N/A@deffn Command halt @option{--no-apm}
2N/AThe command halts the computer. If the @option{--no-apm} option
2N/Ais specified, no APM BIOS call is performed. Otherwise, the computer
2N/Ais shut down using APM.
2N/A@deffn Command help [pattern @dots{}]
2N/ADisplay helpful information about builtin commands. If you do not
2N/Aspecify @var{pattern}, this command shows short descriptions of all
2N/AIf you specify any @var{patterns}, it displays longer information
2N/Aabout each of the commands whose names begin with those @var{patterns}.
2N/A@deffn Command initrd file
2N/ALoad an initial ramdisk for a Linux kernel image, and set the appropriate
2N/Aparameters in the Linux setup area in memory. This may only be used after
2N/Athe @command{linux} command (@pxref{linux}) has been run. See also
2N/A@deffn Command initrd16 file
2N/ALoad an initial ramdisk for a Linux kernel image to be booted in 16-bit
2N/Amode, and set the appropriate parameters in the Linux setup area in memory.
2N/AThis may only be used after the @command{linux16} command (@pxref{linux16})
2N/AThis command is only available on x86 systems.
2N/A@deffn Command insmod module
2N/AInsert the dynamic GRUB module called @var{module}.
2N/A@subsection keystatus
2N/A@deffn Command keystatus [@option{--shift}] [@option{--ctrl}] [@option{--alt}]
2N/AReturn true if the Shift, Control, or Alt modifier keys are held down, as
2N/Arequested by options. This is useful in scripting, to allow some user
2N/Acontrol over behaviour without having to wait for a keypress.
2N/AChecking key modifier status is only supported on some platforms. If invoked
2N/Awithout any options, the @command{keystatus} command returns true if and
2N/Aonly if checking key modifier status is supported.
2N/A@deffn Command linux file @dots{}
2N/ALoad a Linux kernel image from @var{file}. The rest of the line is passed
2N/Averbatim as the @dfn{kernel command-line}. Any initrd must be reloaded
2N/Aafter using this command (@pxref{initrd}).
2N/AOn x86 systems, the kernel will be booted using the 32-bit boot protocol.
2N/ANote that this means that the @samp{vga=} boot option will not work; if you
2N/Awant to set a special video mode, you will need to use GRUB commands such as
2N/A@samp{set gfxpayload=1024x768} or @samp{set gfxpayload=keep} (to keep the
2N/Asame mode as used in GRUB) instead. GRUB can automatically detect some uses
2N/Aof @samp{vga=} and translate them to appropriate settings of
2N/A@samp{gfxpayload}. The @command{linux16} command (@pxref{linux16}) avoids
2N/A@deffn Command linux16 file @dots{}
2N/ALoad a Linux kernel image from @var{file} in 16-bit mode. The rest of the
2N/Aline is passed verbatim as the @dfn{kernel command-line}. Any initrd must
2N/Abe reloaded after using this command (@pxref{initrd16}).
2N/AThe kernel will be booted using the traditional 16-bit boot protocol. As
2N/Awell as bypassing problems with @samp{vga=} described in @ref{linux}, this
2N/Apermits booting some other programs that implement the Linux boot protocol
2N/Afor the sake of convenience.
2N/AThis command is only available on x86 systems.
2N/A@deffn Command list_env [@option{-f} file]
2N/AList all variables in the environment block file. @xref{Environment block}.
2N/AThe @option{-f} option overrides the default location of the environment
2N/A@deffn Command load_env [@option{-f} file]
2N/ALoad all variables from the environment block file into the environment.
2N/A@xref{Environment block}.
2N/AThe @option{-f} option overrides the default location of the environment
2N/A@deffn Command loopback [@option{-d}] device file
2N/AMake the device named @var{device} correspond to the contents of the
2N/Afilesystem image in @var{file}. For example:
2N/AWith the @option{-d} option, delete a device previously created using this
2N/A@deffn Command ls [arg @dots{}]
2N/AList devices or files.
2N/AWith no arguments, print all devices known to GRUB.
2N/AIf the argument is a device name enclosed in parentheses (@pxref{Device
2N/Asyntax}), then list all files at the root directory of that device.
2N/AIf the argument is a directory given as an absolute file name (@pxref{File
2N/Aname syntax}), then list the contents of that directory.
2N/A@deffn Command normal [file]
2N/AEnter normal mode and display the GRUB menu.
2N/AIn normal mode, commands, filesystem modules, and cryptography modules are
2N/Aautomatically loaded, and the full GRUB script parser is available. Other
2N/Amodules may be explicitly loaded using @command{insmod} (@pxref{insmod}).
2N/AIf a @var{file} is given, then commands will be read from that file.
2N/A@command{normal} may be called from within normal mode, creating a nested
2N/Aenvironment. It is more usual to use @command{configfile}
2N/A(@pxref{configfile}) for this.
2N/A@subsection normal_exit
2N/A@deffn Command normal_exit
2N/AExit normal mode (@pxref{normal}). If this instance of normal mode was not
2N/Anested within another one, then return to rescue mode.
2N/A@deffn Command parttool partition commands
2N/AMake various modifications to partition table entries.
2N/AEach @var{command} is either a boolean option, in which case it must be
2N/Afollowed with @samp{+} or @samp{-} (with no intervening space) to enable or
2N/Adisable that option, or else it takes a value in the form
2N/A@samp{@var{command}=@var{value}}.
2N/ACurrently, @command{parttool} is only useful on DOS partition tables (also
2N/Aknown as Master Boot Record, or MBR). On these partition tables, the
2N/Afollowing commands are available:
2N/A@item @samp{boot} (boolean)
2N/AWhen enabled, this makes the selected partition be the active (bootable)
2N/Apartition on its disk, clearing the active flag on all other partitions.
2N/AThis command is limited to @emph{primary} partitions.
2N/A@item @samp{type} (value)
2N/AChange the type of an existing partition. The value must be a number in the
2N/Arange 0-0xFF (prefix with @samp{0x} to enter it in hexadecimal).
2N/A@item @samp{hidden} (boolean)
2N/AWhen enabled, this hides the selected partition by setting the @dfn{hidden}
2N/Abit in its partition type code; when disabled, unhides the selected
2N/Apartition by clearing this bit. This is useful only when booting DOS or
2N/AWwindows and multiple primary FAT partitions exist in one disk. See also
2N/A@deffn Command password user clear-password
2N/ADefine a user named @var{user} with password @var{clear-password}.
2N/A@node password_pbkdf2
2N/A@subsection password_pbkdf2
2N/A@deffn Command password_pbkdf2 user hashed-password
2N/ADefine a user named @var{user} with password hash @var{hashed-password}.
2N/AUse @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
2N/Ato generate password hashes. @xref{Security}.
2N/A@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ...
2N/AIf the argument is a file name (@pxref{File name syntax}), play the tune
2N/Arecorded in it. The file format is first the tempo as an unsigned 32bit
2N/Alittle-endian number, then pairs of unsigned 16bit little-endian numbers for
2N/Apitch and duration pairs.
2N/AIf the arguments are a series of numbers, play the inline tune.
2N/AThe tempo is the base for all note durations. 60 gives a 1-second base, 120
2N/Agives a half-second base, etc. Pitches are Hz. Set pitch to 0 to produce
2N/A@subsection pxe_unload
2N/A@deffn Command pxe_unload
2N/AUnload the PXE environment (@pxref{Network}).
2N/AThis command is only available on PC BIOS systems.
2N/A@deffn Command read [var]
2N/ARead a line of input from the user. If an environment variable @var{var} is
2N/Agiven, set that environment variable to the line of input that was read,
2N/Awith no terminating newline.
2N/A@deffn Command reboot
2N/A@deffn Command save_env [@option{-f} file] var @dots{}
2N/ASave the named variables from the environment to the environment block file.
2N/A@xref{Environment block}.
2N/AThe @option{-f} option overrides the default location of the environment
2N/A@deffn Command search @
2N/A [@option{--file}|@option{--label}|@option{--fs-uuid}] @
2N/A [@option{--set} [var]] [@option{--no-floppy}] name
2N/ASearch devices by file (@option{-f}, @option{--file}), filesystem label
2N/A(@option{-l}, @option{--label}), or filesystem UUID (@option{-u},
2N/AIf the @option{--set} option is used, the first device found is set as the
2N/Avalue of environment variable @var{var}. The default variable is
2N/AThe @option{--no-floppy} option prevents searching floppy devices, which can
2N/Acommands are aliases for @samp{search --file}, @samp{search --label}, and
2N/A@samp{search --fs-uuid} respectively.
2N/A@deffn Command sendkey @
2N/A [@option{--num}|@option{--caps}|@option{--scroll}|@option{--insert}|@
2N/A@option{--pause}|@option{--left-shift}|@option{--right-shift}|@
2N/A@option{--sysrq}|@option{--numkey}|@option{--capskey}|@option{--scrollkey}|@
2N/A@option{--insertkey}|@option{--left-alt}|@option{--right-alt}|@
2N/A@option{--left-ctrl}|@option{--right-ctrl} @
2N/A @samp{on}|@samp{off}]@dots{} @
2N/AInsert keystrokes into the keyboard buffer when booting. Sometimes an
2N/Aoperating system or chainloaded boot loader requires particular keys to be
2N/Apressed: for example, one might need to press a particular key to enter
2N/A"safe mode", or when chainloading another boot loader one might send
2N/Akeystrokes to it to navigate its menu.
2N/AYou may provide up to 16 keystrokes (the length of the BIOS keyboard
2N/Abuffer). Keystroke names may be upper-case or lower-case letters, digits,
2N/Aor taken from the following table:
2N/A@c Please keep this table in the same order as in
2N/A@c Exception: The function and numeric keys are sorted, for aesthetics.
2N/A@multitable @columnfractions .4 .5
2N/A@headitem Name @tab Key
2N/A@item escape @tab Escape
2N/A@item numbersign @tab #
2N/A@item ampersand @tab &
2N/A@item asterisk @tab *
2N/A@item parenleft @tab (
2N/A@item parenright @tab )
2N/A@item underscore @tab _
2N/A@item backspace @tab Backspace
2N/A@item bracketleft @tab [
2N/A@item braceleft @tab @{
2N/A@item bracketright @tab ]
2N/A@item braceright @tab @}
2N/A@item enter @tab Enter
2N/A@item control @tab press and release Control
2N/A@item semicolon @tab ;
2N/A@item doublequote @tab "
2N/A@item backquote @tab `
2N/A@item shift @tab press and release left Shift
2N/A@item backslash @tab \
2N/A@item question @tab ?
2N/A@item rshift @tab press and release right Shift
2N/A@item alt @tab press and release Alt
2N/A@item space @tab space bar
2N/A@item capslock @tab Caps Lock
2N/A@item num1 @tab 1 (numeric keypad)
2N/A@item num2 @tab 2 (numeric keypad)
2N/A@item num3 @tab 3 (numeric keypad)
2N/A@item num4 @tab 4 (numeric keypad)
2N/A@item num5 @tab 5 (numeric keypad)
2N/A@item num6 @tab 6 (numeric keypad)
2N/A@item num7 @tab 7 (numeric keypad)
2N/A@item num8 @tab 8 (numeric keypad)
2N/A@item num9 @tab 9 (numeric keypad)
2N/A@item num0 @tab 0 (numeric keypad)
2N/A@item numperiod @tab . (numeric keypad)
2N/A@item numend @tab End (numeric keypad)
2N/A@item numdown @tab Down (numeric keypad)
2N/A@item numpgdown @tab Page Down (numeric keypad)
2N/A@item numleft @tab Left (numeric keypad)
2N/A@item numcenter @tab 5 with Num Lock inactive (numeric keypad)
2N/A@item numright @tab Right (numeric keypad)
2N/A@item numhome @tab Home (numeric keypad)
2N/A@item numup @tab Up (numeric keypad)
2N/A@item numpgup @tab Page Up (numeric keypad)
2N/A@item numinsert @tab Insert (numeric keypad)
2N/A@item numdelete @tab Delete (numeric keypad)
2N/A@item numasterisk @tab * (numeric keypad)
2N/A@item numminus @tab - (numeric keypad)
2N/A@item numplus @tab + (numeric keypad)
2N/A@item numslash @tab / (numeric keypad)
2N/A@item numenter @tab Enter (numeric keypad)
2N/A@item delete @tab Delete
2N/A@item insert @tab Insert
2N/A@item pgdown @tab Page Down
2N/A@item pgup @tab Page Up
2N/A@item right @tab Right
2N/AAs well as keystrokes, the @command{sendkey} command takes various options
2N/Athat affect the BIOS keyboard status flags. These options take an @samp{on}
2N/Aor @samp{off} parameter, specifying that the corresponding status flag be
2N/Aset or unset; omitting the option for a given status flag will leave that
2N/Aflag at its initial state at boot. The @option{--num}, @option{--caps},
2N/A@option{--scroll}, and @option{--insert} options emulate setting the
2N/Acorresponding mode, while the @option{--numkey}, @option{--capskey},
2N/A@option{--scrollkey}, and @option{--insertkey} options emulate pressing and
2N/Aholding the corresponding key. The other status flag options are
2N/AIf the @option{--no-led} option is given, the status flag options will have
2N/Ano effect on keyboard LEDs.
2N/AIf the @command{sendkey} command is given multiple times, then only the last
2N/Ainvocation has any effect.
2N/ASince @command{sendkey} manipulates the BIOS keyboard buffer, it may cause
2N/Ahangs, reboots, or other misbehaviour on some systems. If the operating
2N/Asystem or boot loader that runs after GRUB uses its own keyboard driver
2N/Arather than the BIOS keyboard functions, then @command{sendkey} will have no
2N/AThis command is only available on PC BIOS systems.
2N/A@deffn Command set [envvar=value]
2N/ASet the environment variable @var{envvar} to @var{value}. If invoked with no
2N/Aarguments, print all environment variables with their values.
2N/ADo nothing, successfully. This is mainly useful in control constructs such
2N/Aas @code{if} and @code{while} (@pxref{Shell-like scripting}).
2N/A@deffn Command unset envvar
2N/AUnset the environment variable @var{envvar}.
2N/AThis command is not yet implemented for GRUB 2, although it is planned.
2N/A@node Internationalisation
2N/AGRUB uses UTF-8 internally other than in rendering where some GRUB-specific
2N/Aappropriate representation is used. All text files (including config) are
2N/Aassumed to be encoded in UTF-8.
2N/ANTFS, JFS, UDF, HFS+, exFAT, long filenames in FAT, Joliet part of
2N/AISO9660 are treated as UTF-16 as per specification. AFS and BFS are read
2N/Aas UTF-8, again according to specification. BtrFS, cpio, tar, squash4, minix,
2N/Aminix2, minix3, ROMFS, ReiserFS, XFS, ext2, ext3, ext4, FAT (short names),
2N/AISO9660 (plain and RockRidge), nilfs2, UFS1, UFS2 and ZFS are assumed
2N/Ato be UTF-8. This might be false on systems configured with legacy charset
2N/Abut as long as the charset used is superset of ASCII you should be able to
2N/Aaccess ASCII-named files. And it's recommended to configure your system to use
2N/AUTF-8 to access the filesystem, convmv may help with migration. AFFS, SFS
2N/Aand HFS never use unicode and GRUB assumes them to be in Latin1, Latin1
2N/Aand MacRoman respectively. GRUB handles filesystem case-insensitivity however
2N/Ano attempt is performed at case conversion of international characters
2N/Aso
e.g. a file named lowercase greek alpha is treated as different from
2N/Athe one named as uppercase alpha. The filesystems in questions are
2N/ANTFS (except POSIX namespace), HFS+ (by default), FAT, exFAT and
2N/AZFS (configurable on per-subvolume basis by property ``casesensitivity'',
2N/Adefault sensitive). On ZFS subvolumes marked as case insensitive files
2N/Acontaining lowercase international characters are inaccessible.
2N/AAlso like all supported filesystems except HFS+ and ZFS (configurable on
2N/Aper-subvolume basis by property ``normalization'', default none) GRUB makes
2N/Ano attempt at check of canonical equivalence so a file name u-diaresis is
2N/Atreated as distinct from u+combining diaresis. This however means that in
2N/Aorder to access file on HFS+ its name must be specified in normalisation form D.
2N/AOn normalized ZFS subvolumes filenames out of normalisation are inaccessible.
2N/A@chapter Output terminal
2N/AFirmware output console ``console'' on ARC and IEEE1275 are limited to ASCII.
2N/ABIOS firmware console and VGA text are limited to ASCII and some pseudographics.
2N/ANone of above mentioned is appropriate for displaying international and any
2N/Aunsupported character is replaced with question mark except pseudographics
2N/Awhich we attempt to approximate with ASCII. EFI console on the other hand
2N/Anominally supports UTF-16 but actual language coverage depends on firmware and
2N/Amay be very limited. The encoding used on serial can be chosen with
2N/A@command{terminfo} as either ASCII, UTF-8 or ``visual UTF-8''. Last one is
2N/Aagainst the specification but results in correct rendering of right-to-left
2N/Aon some readers which don't have own bidi implementation. When using gfxterm
2N/Aor gfxmenu GRUB itself is responsible for rendering the text. In this case
2N/AGRUB is limited by loaded fonts. If fonts contain all required characters
2N/Athen bidirectional text, cursive variants and combining marks other than
2N/Aenclosing, half (
e.g. left half tilde or combining overline) and double ones.
2N/ALigatures aren't supported though. This should cover European, Middle Eastern
2N/A(if you don't mind lack of lam-alif ligature in Arabic) and East Asian scripts.
2N/ANotable unsupported scripts are Brahmic family and derived as well as
2N/AMongolian, Tifinagh, Korean Jamo (precomposed characters have no problem)
2N/Aand tonal writing (2e5-2e9). GRUB also ignores deprecated (as specified
2N/Ain Unicode) characters (
e.g. tags). GRUB also doesn't handle so called
2N/A``annotation characters'' If you can complete either of
2N/Atwo lists or, better, propose a patch to improve rendering, please contact
2N/A@chapter Input terminal
2N/AFirmware console on BIOS, IEEE1275 and ARC doesn't allow you to enter non-ASCII
2N/Acharacters. EFI specification allows for such but author is unaware of any
2N/Aactual implementations. Serial input is currently limited for latin1 (unlikely
2N/Ato change). Own keyboard implementations (at_keyboard and usb_keyboard) can
2N/Asupport any characters but work on one-char-per-keystroke. So no dead keys or
2N/Aadvanced input method. Also there is no keymap change hotkey. In practice it
2N/Amakes difficult to enter any text using non-Latin alphabet.
2N/AGRUB supports being translated. For this you need to have language *.mo files in $
prefix/locale, load gettext module and set ``lang'' variable.
2N/ARegexps work on unicode characters, however no attempt at checking cannonical
2N/Aequivalence has been made. Moreover the classes like [:alpha:] match only
2N/AIEEE1275 aliases are matched case-insensitively except non-ASCII which is
2N/Amatched as binary. Similar behaviour is for matching OSBundleRequired.
2N/ASince IEEE1275 aliases and OSBundleRequired don't contain any non-ASCII it
2N/Ashould never be a problem in practice.
2N/A@chapter Authentication and authorisation
2N/ABy default, the boot loader interface is accessible to anyone with physical
2N/Aaccess to the console: anyone can select and edit any menu entry, and anyone
2N/Acan get direct access to a GRUB shell prompt. For most systems, this is
2N/Areasonable since anyone with direct physical access has a variety of other
2N/Aways to gain full access, and requiring authentication at the boot loader
2N/Alevel would only serve to make it difficult to recover broken systems.
2N/AHowever, in some environments, such as kiosks, it may be appropriate to lock
2N/Adown the boot loader to require authentication before performing certain
2N/AThe @samp{password} (@pxref{password}) and @samp{password_pbkdf2}
2N/A(@pxref{password_pbkdf2}) commands can be used to define users, each of
2N/Awhich has an associated password. @samp{password} sets the password in
2N/Aplain text, requiring @file{
grub.cfg} to be secure; @samp{password_pbkdf2}
2N/Asets the password hashed using the Password-Based Key Derivation Function
2N/A(RFC 2898), requiring the use of @command{grub-mkpasswd-pbkdf2}
2N/A(@pxref{Invoking grub-mkpasswd-pbkdf2}) to generate password hashes.
2N/AIn order to enable authentication support, the @samp{superusers} environment
2N/Avariable must be set to a list of usernames, separated by any of spaces,
2N/Acommas, semicolons, pipes, or ampersands. Superusers are permitted to use
2N/Athe GRUB command line, edit menu entries, and execute any menu entry. If
2N/A@samp{superusers} is set, then use of the command line is automatically
2N/Arestricted to superusers.
2N/AOther users may be given access to specific menu entries by giving a list of
2N/Ausernames (as above) using the @option{--users} option to the
2N/A@samp{menuentry} command (@pxref{menuentry}). If the @option{--users}
2N/Aoption is not used for a menu entry, then that entry is unrestricted.
2N/APutting this together, a typical @file{
grub.cfg} fragment might look like
2N/Aset superusers="root"
2N/Apassword user1 insecure
2N/Amenuentry "May be run by any user" @{
2N/Amenuentry "Superusers only" --users "" @{
2N/A linux /vmlinuz single
2N/Amenuentry "May be run by user1 or a superuser" --users user1 @{
2N/AThe @command{grub-mkconfig} program does not yet have built-in support for
2N/Agenerating configuration files with authentication. You can use
2N/A@file{
/etc/grub.d/40_custom} to add simple superuser authentication, by
2N/Aadding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
2N/A@node Supported kernels
2N/A@chapter Supported boot targets
2N/AX86 support is summarised in the following table. ``Yes'' means that the kernel works on the given platform, ``crashes'' means an early kernel crash which we hope will be fixed by concerned kernel developers. ``no'' means GRUB doesn't load the given kernel on a given platform. ``headless'' means that the kernel works but lacks console drivers (you can still use serial or network console). In case of ``no'' and ``crashes'' the reason is given in footnote.
2N/A@multitable @columnfractions .50 .22 .22
2N/A@item @tab BIOS @tab Coreboot
2N/A@item BIOS chainloading @tab yes @tab no (1)
2N/A@item NTLDR @tab yes @tab no (1)
2N/A@item Plan9 @tab yes @tab no (1)
2N/A@item Freedos @tab yes @tab no (1)
2N/A@item FreeBSD bootloader @tab yes @tab crashes (1)
2N/A@item 32-bit kFreeBSD @tab yes @tab crashes (2,6)
2N/A@item 64-bit kFreeBSD @tab yes @tab crashes (2,6)
2N/A@item 32-bit kNetBSD @tab yes @tab crashes (1)
2N/A@item 64-bit kNetBSD @tab yes @tab crashes (2)
2N/A@item 32-bit kOpenBSD @tab yes @tab yes
2N/A@item 64-bit kOpenBSD @tab yes @tab yes
2N/A@item Multiboot @tab yes @tab yes
2N/A@item Multiboot2 @tab yes @tab yes
2N/A@item 32-bit Linux (legacy protocol) @tab yes @tab no (1)
2N/A@item 64-bit Linux (legacy protocol) @tab yes @tab no (1)
2N/A@item 32-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 64-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 32-bit XNU @tab yes @tab ?
2N/A@item 64-bit XNU @tab yes @tab ?
2N/A@item 32-bit EFI chainloader @tab no (3) @tab no (3)
2N/A@item 64-bit EFI chainloader @tab no (3) @tab no (3)
2N/A@item Appleloader @tab no (3) @tab no (3)
2N/A@multitable @columnfractions .50 .22 .22
2N/A@item @tab Multiboot @tab Qemu
2N/A@item BIOS chainloading @tab no (1) @tab no (1)
2N/A@item NTLDR @tab no (1) @tab no (1)
2N/A@item Plan9 @tab no (1) @tab no (1)
2N/A@item FreeDOS @tab no (1) @tab no (1)
2N/A@item FreeBSD bootloader @tab crashes (1) @tab crashes (1)
2N/A@item 32-bit kFreeBSD @tab crashes (6) @tab crashes (6)
2N/A@item 64-bit kFreeBSD @tab crashes (6) @tab crashes (6)
2N/A@item 32-bit kNetBSD @tab crashes (1) @tab crashes (1)
2N/A@item 64-bit kNetBSD @tab yes @tab yes
2N/A@item 32-bit kOpenBSD @tab yes @tab yes
2N/A@item 64-bit kOpenBSD @tab yes @tab yes
2N/A@item Multiboot @tab yes @tab yes
2N/A@item Multiboot2 @tab yes @tab yes
2N/A@item 32-bit Linux (legacy protocol) @tab no (1) @tab no (1)
2N/A@item 64-bit Linux (legacy protocol) @tab no (1) @tab no (1)
2N/A@item 32-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 64-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 32-bit XNU @tab ? @tab ?
2N/A@item 64-bit XNU @tab ? @tab ?
2N/A@item 32-bit EFI chainloader @tab no (3) @tab no (3)
2N/A@item 64-bit EFI chainloader @tab no (3) @tab no (3)
2N/A@item Appleloader @tab no (3) @tab no (3)
2N/A@multitable @columnfractions .50 .22 .22
2N/A@item @tab 32-bit EFI @tab 64-bit EFI
2N/A@item BIOS chainloading @tab no (1) @tab no (1)
2N/A@item NTLDR @tab no (1) @tab no (1)
2N/A@item Plan9 @tab no (1) @tab no (1)
2N/A@item FreeDOS @tab no (1) @tab no (1)
2N/A@item FreeBSD bootloader @tab crashes (1) @tab crashes (1)
2N/A@item 32-bit kFreeBSD @tab headless @tab headless
2N/A@item 64-bit kFreeBSD @tab headless @tab headless
2N/A@item 32-bit kNetBSD @tab crashes (1) @tab crashes (1)
2N/A@item 64-bit kNetBSD @tab yes @tab yes
2N/A@item 32-bit kOpenBSD @tab headless @tab headless
2N/A@item 64-bit kOpenBSD @tab headless @tab headless
2N/A@item Multiboot @tab yes @tab yes
2N/A@item Multiboot2 @tab yes @tab yes
2N/A@item 32-bit Linux (legacy protocol) @tab no (1) @tab no (1)
2N/A@item 64-bit Linux (legacy protocol) @tab no (1) @tab no (1)
2N/A@item 32-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 64-bit Linux (modern protocol) @tab yes @tab yes
2N/A@item 32-bit XNU @tab yes @tab yes
2N/A@item 64-bit XNU @tab yes (5) @tab yes
2N/A@item 32-bit EFI chainloader @tab yes @tab no (4)
2N/A@item 64-bit EFI chainloader @tab no (4) @tab yes
2N/A@item Appleloader @tab yes @tab yes
2N/A@multitable @columnfractions .50 .22 .22
2N/A@item BIOS chainloading @tab no (1)
2N/A@item NTLDR @tab no (1)
2N/A@item Plan9 @tab no (1)
2N/A@item FreeDOS @tab no (1)
2N/A@item FreeBSD bootloader @tab crashes (1)
2N/A@item 32-bit kFreeBSD @tab crashes (6)
2N/A@item 64-bit kFreeBSD @tab crashes (6)
2N/A@item 32-bit kNetBSD @tab crashes (1)
2N/A@item 64-bit kNetBSD @tab ?
2N/A@item 32-bit kOpenBSD @tab ?
2N/A@item 64-bit kOpenBSD @tab ?
2N/A@item Multiboot @tab ?
2N/A@item Multiboot2 @tab ?
2N/A@item 32-bit Linux (legacy protocol) @tab no (1)
2N/A@item 64-bit Linux (legacy protocol) @tab no (1)
2N/A@item 32-bit Linux (modern protocol) @tab ?
2N/A@item 64-bit Linux (modern protocol) @tab ?
2N/A@item 32-bit XNU @tab ?
2N/A@item 64-bit XNU @tab ?
2N/A@item 32-bit EFI chainloader @tab no (3)
2N/A@item 64-bit EFI chainloader @tab no (3)
2N/A@item Appleloader @tab no (3)
2N/A@item Crashes because the memory at 0x0-0x1000 isn't available
2N/A@item 32-bit and 64-bit EFI have different structures and work in different CPU modes so it's not possible to chainload 32-bit bootloader on 64-bit platform and vice-versa
2N/A@item Some modules may need to be disabled
2N/APowerPC and Sparc ports support only Linux. MIPS port supports Linux and multiboot2.
2N/AAs you have seen in previous chapter the support matrix is pretty big and some of the configurations are only rarely used. To ensure the quality bootchecks are available for all x86 targets except EFI chainloader, Appleloader and XNU. All x86 platforms have bootcheck facility except ieee1275. Multiboot, multiboot2, BIOS chainloader, ntldr and freebsd-bootloader boot targets are tested only with a fake kernel images. Only Linux is tested among the payloads using Linux protocols.
2N/AFollowing variables must be defined:
2N/A@multitable @columnfractions .30 .65
2N/A@item GRUB_PAYLOADS_DIR @tab directory containing the required kernels
2N/A@item GRUB_CBFSTOOL @tab cbfstoll from Coreboot package (for coreboot platform only)
2N/A@item GRUB_COREBOOT_ROM @tab empty Coreboot ROM
2N/A@item GRUB_QEMU_OPTS @tab additional options to be supplied to QEMU
2N/A@multitable @columnfractions .40 .55
2N/A@node Troubleshooting
2N/A@chapter Error messages produced by GRUB
2N/A* GRUB only offers a rescue shell::
2N/A@node GRUB only offers a rescue shell
2N/A@section GRUB only offers a rescue shell
2N/AGRUB's normal start-up procedure involves setting the @samp{prefix}
2N/Aenvironment variable to a value set in the core image by
2N/A@command{grub-install}, setting the @samp{root} variable to match, loading
2N/Athe @samp{normal} module from the prefix, and running the @samp{normal}
2N/Acommand (@pxref{normal}). This command is responsible for reading
2N/Athings GRUB is supposed to do.
2N/AIf, instead, you only get a rescue shell, this usually means that GRUB
2N/Afailed to load the @samp{normal} module for some reason. It may be possible
2N/Ato work around this temporarily: for instance, if the reason for the failure
2N/Ais that @samp{prefix} is wrong (perhaps it refers to the wrong device, or
2N/Aperhaps the path to @file{
/boot/grub} was not correctly made relative to the
2N/Adevice), then you can correct this and enter normal mode manually:
2N/A# Inspect the current prefix (and other preset variables):
2N/A# Find out which devices are available:
2N/A# Set to the correct value, which might be something like this:
2N/Aset prefix=(hd0,1)/grub
2N/AHowever, any problem that leaves you in the rescue shell probably means that
2N/AGRUB was not correctly installed. It may be more useful to try to reinstall
2N/Ait properly using @kbd{grub-install @var{device}} (@pxref{Invoking
2N/Agrub-install}). When doing this, there are a few things to remember:
2N/ADrive ordering in your operating system may not be the same as the boot
2N/Adrive ordering used by your firmware. Do not assume that your first hard
2N/A@file{
device.map} (@pxref{Device map}) can be used to override this, but it
2N/Ais usually better to use UUIDs or file system labels and avoid depending on
2N/Adrive ordering entirely.
2N/AAt least on BIOS systems, if you tell @command{grub-install} to install GRUB
2N/Ato a partition but GRUB has already been installed in the master boot
2N/Arecord, then the GRUB installation in the partition will be ignored.
2N/AIf possible, it is generally best to avoid installing GRUB to a partition
2N/A(unless it is a special partition for the use of GRUB alone, such as the
2N/ABIOS Boot Partition used on GPT). Doing this means that GRUB may stop being
2N/Aable to read its core image due to a file system moving blocks around, such
2N/Aas while defragmenting, running checks, or even during normal operation.
2N/AInstalling to the whole disk device is normally more robust.
2N/ACheck that GRUB actually knows how to read from the device and file system
2N/Acontaining @file{
/boot/grub}. It will not be able to read from encrypted
2N/Adevices, nor from file systems for which support has not yet been added to
2N/A@node Invoking grub-install
2N/A@chapter Invoking grub-install
2N/AThe program @command{grub-install} installs GRUB on your drive using
2N/A@command{grub-mkimage} and (on some platforms) @command{grub-setup}. You
2N/Amust specify the device name on which you want to install GRUB, like this:
2N/Agrub-install @var{install_device}
2N/AThe device name @var{install_device} is an OS device name or a GRUB
2N/A@command{grub-install} accepts the following options:
2N/APrint a summary of the command-line options and exit.
2N/APrint the version number of GRUB and exit.
2N/A@item --boot-directory=@var{dir}
2N/AInstall GRUB images under the directory @file{@var{dir}/grub/}
2N/AThis option is useful when you want to install GRUB into a
2N/Aseparate partition or a removable disk.
2N/AIf this option is not specified then it defaults to @file{/boot}, so
2N/AHere is an example in which you have a separate @dfn{boot} partition which is
2N/A@node Invoking grub-mkconfig
2N/A@chapter Invoking grub-mkconfig
2N/AThe program @command{grub-mkconfig} generates a configuration file for GRUB
2N/A(@pxref{Simple configuration}).
2N/A@command{grub-mkconfig} accepts the following options:
2N/APrint a summary of the command-line options and exit.
2N/APrint the version number of GRUB and exit.
2N/A@itemx --output=@var{file}
2N/ASend the generated configuration file to @var{file}. The default is to send
2N/Ait to standard output.
2N/A@node Invoking grub-mkpasswd-pbkdf2
2N/A@chapter Invoking grub-mkpasswd-pbkdf2
2N/AThe program @command{grub-mkpasswd-pbkdf2} generates password hashes for
2N/AGRUB (@pxref{Security}).
2N/A@command{grub-mkpasswd-pbkdf2} accepts the following options:
2N/A@item -c @var{number}
2N/A@itemx --iteration-count=@var{number}
2N/ANumber of iterations of the underlying pseudo-random function. Defaults to
2N/A@item -l @var{number}
2N/A@itemx --buflen=@var{number}
2N/ALength of the generated hash. Defaults to 64.
2N/A@item -s @var{number}
2N/A@itemx --salt=@var{number}
2N/ALength of the salt. Defaults to 64.
2N/A@node Invoking grub-mkrescue
2N/A@chapter Invoking grub-mkrescue
2N/AThe program @command{grub-mkrescue} generates a bootable GRUB rescue image
2N/A(@pxref{Making a GRUB bootable CD-ROM}).
2N/AAll arguments not explicitly listed as @command{grub-mkrescue} options are
2N/Apassed on directly to @command{xorriso} in @command{mkisofs} emulation mode.
2N/AOptions passed to @command{xorriso} will normally be interpreted as
2N/A@command{mkisofs} options; if the option @samp{--} is used, then anything
2N/Aafter that will be interpreted as native @command{xorriso} options.
2N/ANon-option arguments specify additional source directories. This is
2N/Acommonly used to add extra files to the image:
2N/A@command{grub-mkrescue} accepts the following options:
2N/APrint a summary of the command-line options and exit.
2N/APrint the version number of GRUB and exit.
2N/A@itemx --output=@var{file}
2N/ASave output in @var{file}. This "option" is required.
2N/A@item --modules=@var{modules}
2N/APre-load the named GRUB modules in the image. Multiple entries in
2N/A@var{modules} should be separated by whitespace (so you will probably need
2N/Ato quote this for your shell).
2N/A@item --rom-directory=@var{dir}
2N/AIf generating images for the QEMU or Coreboot platforms, copy the resulting
2N/Adirectory as well as including them in the image.
2N/A@item --xorriso=@var{file}
2N/AUse @var{file} as the @command{xorriso} program, rather than the built-in
2N/A@item --grub-mkimage=@var{file}
2N/AUse @var{file} as the @command{grub-mkimage} program, rather than the
2N/A@node Obtaining and Building GRUB
2N/A@appendix How to obtain and build GRUB
2N/A@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
2N/AGNU assembler has been changed so that it can produce real 16bits
2N/Ahow to get the latest version.
2N/AGRUB is available from the GNU alpha archive site
2N/A@value{VERSION}, so the file you should grab is:
2N/ATo unbundle GRUB use the instruction:
2N/Awhich will create a directory called @file{grub-@value{VERSION}} with
2N/Aall the sources. You can look at the file @file{INSTALL} for detailed
2N/Ainstructions on how to build and install GRUB, but you should be able to
2N/A@kbd{cd grub-@value{VERSION}}
2N/AAlso, the latest version is available using Bazaar. See
2N/A@appendix Reporting bugs
2N/AThese are the guideline for how to report bugs. Take a look at this
2N/Alist below before you submit bugs:
2N/ABefore getting unsettled, read this manual through and through. Also,
2N/AAlways mention the information on your GRUB. The version number and the
2N/Aconfiguration are quite important. If you build it yourself, write the
2N/Aoptions specified to the configure script and your operating system,
2N/Aincluding the versions of gcc and binutils.
2N/AIf you have trouble with the installation, inform us of how you
2N/Ainstalled GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
2N/Aup when it boots} is not enough.
2N/AThe information on your hardware is also essential. These are especially
2N/Aimportant: the geometries and the partition tables of your hard disk
2N/Adrives and your BIOS.
2N/AIf GRUB cannot boot your operating system, write down
2N/A@emph{everything} you see on the screen. Don't paraphrase them, like
2N/A@samp{The foo OS crashes with GRUB, even though it can boot with the
2N/Abar boot loader just fine}. Mention the commands you executed, the
2N/Amessages printed by them, and information on your operating system
2N/Aincluding the version number.
2N/AExplain what you wanted to do. It is very useful to know your purpose
2N/Aand your wish, and how GRUB didn't satisfy you.
2N/AIf you can investigate the problem yourself, please do. That will give
2N/Ayou and us much more information on the problem. Attaching a patch is
2N/AWhen you attach a patch, make the patch in unified diff format, and
2N/Awrite ChangeLog entries. But, even when you make a patch, don't forget
2N/Ato explain the problem, so that we can understand what your patch is
2N/AWrite down anything that you think might be related. Please understand
2N/Athat we often need to reproduce the same problem you encountered in our
2N/Aenvironment. So your information should be sufficient for us to do the
2N/Asame thing---Don't forget that we cannot see your computer directly. If
2N/Ayou are not sure whether to state a fact or leave it out, state it!
2N/AReporting too many things is much better than omitting something
2N/AIf you follow the guideline above, submit a report to the
2N/AAlternatively, you can submit a report via electronic mail to
2N/A@email{bug-grub@@
gnu.org}, but we strongly recommend that you use the
2N/ABug Tracking System, because e-mail can be passed over easily.
2N/AOnce we get your report, we will try to fix the bugs.
2N/A@appendix Where GRUB will go
2N/AGRUB 2 is now quite stable and used in many production systems. We are
2N/Acurrently working towards a 2.0 release.
2N/AIf you are interested in the development of GRUB 2, take a look at
2N/A@node Copying This Manual
2N/A@appendix Copying This Manual
2N/A* GNU Free Documentation License:: License for copying this manual.
2N/A@c Currently, we use only the Concept Index.
2N/A This is an attempt to make a manual for GRUB 2. The contents are
2N/A copied from the GRUB manual in GRUB Legacy, so they are not always
2N/A appropriate yet for GRUB 2.
