6 @settitle GNU GRUB Manual @value{VERSION}
7 @c Unify all our little indices for now.
15 @footnotestyle separate
20 This manual is for GNU GRUB (version @value{VERSION},
23 Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012,2013 Free Software Foundation, Inc.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.2 or
28 any later version published by the Free Software Foundation; with no
35 * GRUB: (grub). The GRand Unified Bootloader
36 * grub-install: (grub)Invoking grub-install. Install GRUB on your drive
37 * grub-mkconfig: (grub)Invoking grub-mkconfig. Generate GRUB configuration
38 * grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
39 * grub-mkrelpath: (grub)Invoking grub-mkrelpath.
40 * grub-mkrescue: (grub)Invoking grub-mkrescue. Make a GRUB rescue image
41 * grub-mount: (grub)Invoking grub-mount. Mount a file system using GRUB
42 * grub-probe: (grub)Invoking grub-probe. Probe device information
43 * grub-script-check: (grub)Invoking grub-script-check.
46 @setchapternewpage odd
50 @title the GNU GRUB manual
51 @subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
52 @author Gordon Matzigkeit
53 @author Yoshinori K. Okuji
55 @author Colin D. Bennett
56 @c The following two commands start the copyright page.
58 @vskip 0pt plus 1filll
62 @c Output the table of contents at the beginning.
72 This is the documentation of GNU GRUB, the GRand Unified Bootloader,
73 a flexible and powerful boot loader program for a wide range of
76 This edition documents version @value{VERSION}.
82 * Introduction:: Capturing the spirit of GRUB
83 * Naming convention:: Names of your drives in GRUB
84 * OS-specific notes about grub tools::
85 Some notes about OS-specific behaviour of GRUB
87 * Installation:: Installing GRUB on your drive
88 * Booting:: How to boot different operating systems
89 * Configuration:: Writing your own configuration file
90 * Theme file format:: Format of GRUB theme files
91 * Network:: Downloading OS images from a network
92 * Serial terminal:: Using GRUB via a serial line
93 * Vendor power-on keys:: Changing GRUB behaviour on vendor power-on keys
94 * Images:: GRUB image files
95 * Core image size limitation:: GRUB image files size limitations
96 * Filesystem:: Filesystem syntax and semantics
97 * Interface:: The menu and the command-line
98 * Environment:: GRUB environment variables
99 * Commands:: The list of available builtin commands
100 * Internationalisation:: Topics relating to language support
101 * Security:: Authentication, authorisation, and signatures
102 * Platform limitations:: The list of platform-specific limitations
103 * Platform-specific operations:: Platform-specific operations
104 * Supported kernels:: The list of supported kernels
105 * Troubleshooting:: Error messages produced by GRUB
106 * Invoking grub-install:: How to use the GRUB installer
107 * Invoking grub-mkconfig:: Generate a GRUB configuration file
108 * Invoking grub-mkpasswd-pbkdf2::
109 Generate GRUB password hashes
110 * Invoking grub-mkrelpath:: Make system path relative to its root
111 * Invoking grub-mkrescue:: Make a GRUB rescue image
112 * Invoking grub-mount:: Mount a file system using GRUB
113 * Invoking grub-probe:: Probe device information for GRUB
114 * Invoking grub-script-check:: Check GRUB script file for syntax errors
115 * Obtaining and Building GRUB:: How to obtain and build GRUB
116 * Reporting bugs:: Where you should send a bug report
117 * Future:: Some future plans on GRUB
118 * Copying This Manual:: Copying This Manual
124 @chapter Introduction to GRUB
127 * Overview:: What exactly GRUB is and how to use it
128 * History:: From maggot to house fly
129 * Changes from GRUB Legacy:: Differences from previous versions
130 * Features:: GRUB features
131 * Role of a boot loader:: The role of a boot loader
138 Briefly, a @dfn{boot loader} is the first software program that runs when
139 a computer starts. It is responsible for loading and transferring
140 control to an operating system @dfn{kernel} software (such as Linux or
141 GNU Mach). The kernel, in turn, initializes the rest of the operating
142 system (e.g. a GNU system).
144 GNU GRUB is a very powerful boot loader, which can load a wide variety
145 of free operating systems, as well as proprietary operating systems with
146 chain-loading@footnote{@dfn{chain-load} is the mechanism for loading
147 unsupported operating systems by loading another boot loader. It is
148 typically used for loading DOS or Windows.}. GRUB is designed to
149 address the complexity of booting a personal computer; both the
150 program and this manual are tightly bound to that computer platform,
151 although porting to other platforms may be addressed in the future.
153 One of the important features in GRUB is flexibility; GRUB understands
154 filesystems and kernel executable formats, so you can load an arbitrary
155 operating system the way you like, without recording the physical
156 position of your kernel on the disk. Thus you can load the kernel
157 just by specifying its file name and the drive and partition where the
160 When booting with GRUB, you can use either a command-line interface
161 (@pxref{Command-line interface}), or a menu interface (@pxref{Menu
162 interface}). Using the command-line interface, you type the drive
163 specification and file name of the kernel manually. In the menu
164 interface, you just select an OS using the arrow keys. The menu is
165 based on a configuration file which you prepare beforehand
166 (@pxref{Configuration}). While in the menu, you can switch to the
167 command-line mode, and vice-versa. You can even edit menu entries
170 In the following chapters, you will learn how to specify a drive, a
171 partition, and a file name (@pxref{Naming convention}) to GRUB, how to
172 install GRUB on your drive (@pxref{Installation}), and how to boot your
173 OSes (@pxref{Booting}), step by step.
177 @section History of GRUB
179 GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
180 Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
181 Mach). Erich and Brian Ford designed the Multiboot Specification
182 (@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
183 Specification}), because they were determined not to add to the large
184 number of mutually-incompatible PC boot methods.
186 Erich then began modifying the FreeBSD boot loader so that it would
187 understand Multiboot. He soon realized that it would be a lot easier
188 to write his own boot loader from scratch than to keep working on the
189 FreeBSD boot loader, and so GRUB was born.
191 Erich added many features to GRUB, but other priorities prevented him
192 from keeping up with the demands of its quickly-expanding user base. In
193 1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
194 official GNU package, and opened its development by making the latest
195 sources available via anonymous CVS. @xref{Obtaining and Building
196 GRUB}, for more information.
198 Over the next few years, GRUB was extended to meet many needs, but it
199 quickly became clear that its design was not keeping up with the extensions
200 being made to it, and we reached the point where it was very difficult to
201 make any further changes without breaking existing features. Around 2002,
202 Yoshinori K. Okuji started work on PUPA (Preliminary Universal Programming
203 Architecture for GNU GRUB), aiming to rewrite the core of GRUB to make it
204 cleaner, safer, more robust, and more powerful. PUPA was eventually renamed
205 to GRUB 2, and the original version of GRUB was renamed to GRUB Legacy.
206 Small amounts of maintenance continued to be done on GRUB Legacy, but the
207 last release (0.97) was made in 2005 and at the time of writing it seems
208 unlikely that there will be another.
210 By around 2007, GNU/Linux distributions started to use GRUB 2 to limited
211 extents, and by the end of 2009 multiple major distributions were installing
215 @node Changes from GRUB Legacy
216 @section Differences from previous versions
218 GRUB 2 is a rewrite of GRUB (@pxref{History}), although it shares many
219 characteristics with the previous version, now known as GRUB Legacy. Users
220 of GRUB Legacy may need some guidance to find their way around this new
225 The configuration file has a new name (@file{grub.cfg} rather than
226 @file{menu.lst} or @file{grub.conf}), new syntax (@pxref{Configuration}) and
227 many new commands (@pxref{Commands}). Configuration cannot be copied over
228 directly, although most GRUB Legacy users should not find the syntax too
232 @file{grub.cfg} is typically automatically generated by
233 @command{grub-mkconfig} (@pxref{Simple configuration}). This makes it
234 easier to handle versioned kernel upgrades.
237 Partition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming
241 The configuration file is now written in something closer to a full
242 scripting language: variables, conditionals, and loops are available.
245 A small amount of persistent storage is available across reboots, using the
246 @command{save_env} and @command{load_env} commands in GRUB and the
247 @command{grub-editenv} utility. This is not available in all configurations
248 (@pxref{Environment block}).
251 GRUB 2 has more reliable ways to find its own files and those of target
252 kernels on multiple-disk systems, and has commands (@pxref{search}) to find
253 devices using file system labels or Universally Unique Identifiers (UUIDs).
256 GRUB 2 is available for several other types of system in addition to the PC
257 BIOS systems supported by GRUB Legacy: PC EFI, PC coreboot, PowerPC, SPARC,
258 and MIPS Lemote Yeeloong are all supported.
261 Many more file systems are supported, including but not limited to ext4,
265 GRUB 2 can read files directly from LVM and RAID devices.
268 A graphical terminal and a graphical menu system are available.
271 GRUB 2's interface can be translated, including menu entry names.
274 The image files (@pxref{Images}) that make up GRUB have been reorganised;
275 Stage 1, Stage 1.5, and Stage 2 are no more.
278 GRUB 2 puts many facilities in dynamically loaded modules, allowing the core
279 image to be smaller, and allowing the core image to be built in more
285 @section GRUB features
287 The primary requirement for GRUB is that it be compliant with the
288 @dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
289 Specification, Motivation, multiboot, The Multiboot Specification}.
291 The other goals, listed in approximate order of importance, are:
295 Basic functions must be straightforward for end-users.
298 Rich functionality to support kernel experts and designers.
301 Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
302 Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
303 supported via a chain-loading function.
306 Except for specific compatibility modes (chain-loading and the Linux
307 @dfn{piggyback} format), all kernels will be started in much the same
308 state as in the Multiboot Specification. Only kernels loaded at 1 megabyte
309 or above are presently supported. Any attempt to load below that
310 boundary will simply result in immediate failure and an error message
311 reporting the problem.
313 In addition to the requirements above, GRUB has the following features
314 (note that the Multiboot Specification doesn't require all the features
318 @item Recognize multiple executable formats
319 Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol
320 tables are also loaded.
322 @item Support non-Multiboot kernels
323 Support many of the various free 32-bit kernels that lack Multiboot
324 compliance (primarily FreeBSD, NetBSD@footnote{The NetBSD/i386 kernel
325 is Multiboot-compliant, but lacks support for Multiboot modules.},
326 OpenBSD, and Linux). Chain-loading of other boot loaders is also
329 @item Load multiples modules
330 Fully support the Multiboot feature of loading multiple modules.
332 @item Load a configuration file
333 Support a human-readable text configuration file with preset boot
334 commands. You can also load another configuration file dynamically and
335 embed a preset configuration file in a GRUB image file. The list of
336 commands (@pxref{Commands}) are a superset of those supported on the
337 command-line. An example configuration file is provided in
340 @item Provide a menu interface
341 A menu interface listing preset boot commands, with a programmable
342 timeout, is available. There is no fixed limit on the number of boot
343 entries, and the current implementation has space for several hundred.
345 @item Have a flexible command-line interface
346 A fairly flexible command-line interface, accessible from the menu,
347 is available to edit any preset commands, or write a new boot command
348 set from scratch. If no configuration file is present, GRUB drops to
351 The list of commands (@pxref{Commands}) are a subset of those supported
352 for configuration files. Editing commands closely resembles the Bash
353 command-line (@pxref{Command Line Editing, Bash, Command Line Editing,
354 features, Bash Features}), with @key{TAB}-completion of commands,
355 devices, partitions, and files in a directory depending on context.
357 @item Support multiple filesystem types
358 Support multiple filesystem types transparently, plus a useful explicit
359 blocklist notation. The currently supported filesystem types are @dfn{Amiga
360 Fast FileSystem (AFFS)}, @dfn{AtheOS fs}, @dfn{BeFS},
361 @dfn{BtrFS} (including raid0, raid1, raid10, gzip and lzo),
362 @dfn{cpio} (little- and big-endian bin, odc and newc variants),
363 @dfn{Linux ext2/ext3/ext4}, @dfn{DOS FAT12/FAT16/FAT32}, @dfn{exFAT}, @dfn{HFS},
364 @dfn{HFS+}, @dfn{ISO9660} (including Joliet, Rock-ridge and multi-chunk files),
365 @dfn{JFS}, @dfn{Minix fs} (versions 1, 2 and 3), @dfn{nilfs2},
366 @dfn{NTFS} (including compression), @dfn{ReiserFS}, @dfn{ROMFS},
367 @dfn{Amiga Smart FileSystem (SFS)}, @dfn{Squash4}, @dfn{tar}, @dfn{UDF},
368 @dfn{BSD UFS/UFS2}, @dfn{XFS}, and @dfn{ZFS} (including lzjb, gzip,
369 zle, mirror, stripe, raidz1/2/3 and encryption in AES-CCM and AES-GCM).
370 @xref{Filesystem}, for more information.
372 @item Support automatic decompression
373 Can decompress files which were compressed by @command{gzip} or
374 @command{xz}@footnote{Only CRC32 data integrity check is supported (xz default
375 is CRC64 so one should use --check=crc32 option). LZMA BCJ filters are
376 supported.}. This function is both automatic and transparent to the user
377 (i.e. all functions operate upon the uncompressed contents of the specified
378 files). This greatly reduces a file size and loading time, a
379 particularly great benefit for floppies.@footnote{There are a few
380 pathological cases where loading a very badly organized ELF kernel might
381 take longer, but in practice this never happen.}
383 It is conceivable that some kernel modules should be loaded in a
384 compressed state, so a different module-loading command can be specified
385 to avoid uncompressing the modules.
387 @item Access data on any installed device
388 Support reading data from any or all floppies or hard disk(s) recognized
389 by the BIOS, independent of the setting of the root device.
391 @item Be independent of drive geometry translations
392 Unlike many other boot loaders, GRUB makes the particular drive
393 translation irrelevant. A drive installed and running with one
394 translation may be converted to another translation without any adverse
395 effects or changes in GRUB's configuration.
397 @item Detect all installed @sc{ram}
398 GRUB can generally find all the installed @sc{ram} on a PC-compatible
399 machine. It uses an advanced BIOS query technique for finding all
400 memory regions. As described on the Multiboot Specification (@pxref{Top,
401 Multiboot Specification, Motivation, multiboot, The Multiboot
402 Specification}), not all kernels make use of this information, but GRUB
403 provides it for those who do.
405 @item Support Logical Block Address mode
406 In traditional disk calls (called @dfn{CHS mode}), there is a geometry
407 translation problem, that is, the BIOS cannot access over 1024
408 cylinders, so the accessible space is limited to at least 508 MB and to
409 at most 8GB. GRUB can't universally solve this problem, as there is no
410 standard interface used in all machines. However, several newer machines
411 have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
412 automatically detects if LBA mode is available and uses it if
413 available. In LBA mode, GRUB can access the entire disk.
415 @item Support network booting
416 GRUB is basically a disk-based boot loader but also has network
417 support. You can load OS images from a network by using the @dfn{TFTP}
420 @item Support remote terminals
421 To support computers with no console, GRUB provides remote terminal
422 support, so that you can control GRUB from a remote host. Only serial
423 terminal support is implemented at the moment.
427 @node Role of a boot loader
428 @section The role of a boot loader
430 The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
433 Some people like to acknowledge both the operating system and kernel when
434 they talk about their computers, so they might say they use
435 ``GNU/Linux'' or ``GNU/Hurd''. Other people seem to think that the
436 kernel is the most important part of the system, so they like to call
437 their GNU operating systems ``Linux systems.''
439 I, personally, believe that this is a grave injustice, because the
440 @emph{boot loader} is the most important software of all. I used to
441 refer to the above systems as either ``LILO''@footnote{The LInux LOader,
442 a boot loader that everybody uses, but nobody likes.} or ``GRUB''
445 Unfortunately, nobody ever understood what I was talking about; now I
446 just use the word ``GNU'' as a pseudonym for GRUB.
448 So, if you ever hear people talking about their alleged ``GNU'' systems,
449 remember that they are actually paying homage to the best boot loader
453 We, the GRUB maintainers, do not (usually) encourage Gordon's level of
454 fanaticism, but it helps to remember that boot loaders deserve
455 recognition. We hope that you enjoy using GNU GRUB as much as we did
459 @node Naming convention
460 @chapter Naming convention
462 The device syntax used in GRUB is a wee bit different from what you may
463 have seen before in your operating system(s), and you need to know it so
464 that you can specify a drive/partition.
466 Look at the following examples and explanations:
472 First of all, GRUB requires that the device name be enclosed with
473 @samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
474 disk. The number @samp{0} is the drive number, which is counted from
475 @emph{zero}. This expression means that GRUB will use the whole floppy
482 Here, @samp{hd} means it is a hard disk drive. The first integer
483 @samp{0} indicates the drive number, that is, the first hard disk,
484 the string @samp{msdos} indicates the partition scheme, while
485 the second integer, @samp{2}, indicates the partition number (or the
486 @sc{pc} slice number in the BSD terminology). The partition numbers are
487 counted from @emph{one}, not from zero (as was the case in previous
488 versions of GRUB). This expression means the second partition of the
489 first hard disk drive. In this case, GRUB uses one partition of the
490 disk, instead of the whole disk.
496 This specifies the first @dfn{extended partition} of the first hard disk
497 drive. Note that the partition numbers for extended partitions are
498 counted from @samp{5}, regardless of the actual number of primary
499 partitions on your hard disk.
505 This means the BSD @samp{a} partition on first @sc{pc} slice number
506 of the second hard disk.
508 Of course, to actually access the disks or partitions with GRUB, you
509 need to use the device specification in a command, like @samp{set
510 root=(fd0)} or @samp{parttool (hd0,msdos3) hidden-}. To help you find out
511 which number specifies a partition you want, the GRUB command-line
512 (@pxref{Command-line interface}) options have argument
513 completion. This means that, for example, you only need to type
519 followed by a @key{TAB}, and GRUB will display the list of drives,
520 partitions, or file names. So it should be quite easy to determine the
521 name of your target partition, even with minimal knowledge of the
524 Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply
525 counts the drive numbers from zero, regardless of their type. Normally,
526 any IDE drive number is less than any SCSI drive number, although that
527 is not true if you change the boot sequence by swapping IDE and SCSI
530 Now the question is, how to specify a file? Again, consider an
537 This specifies the file named @samp{vmlinuz}, found on the first
538 partition of the first hard disk drive. Note that the argument
539 completion works with file names, too.
541 That was easy, admit it. Now read the next chapter, to find out how to
542 actually install GRUB on your drive.
544 @node OS-specific notes about grub tools
545 @chapter OS-specific notes about grub tools
547 On OS which have device nodes similar to Unix-like OS GRUB tools use the
548 OS name. E.g. for GNU/Linux:
551 # @kbd{grub-install /dev/sda}
554 On AROS we use another syntax. For volumes:
566 For disks we use syntax:
568 //:<driver name>/unit/flags
574 # @kbd{grub-install //:ata.device/0/0}
577 On Windows we use UNC path. For volumes it's typically
587 \\?\Volume@{17f34d50-cf64-4b02-800e-51d79c3aa2ff@}
595 \\?\PhysicalDrive<number>
601 # @kbd{grub-install \\?\PhysicalDrive0}
604 Beware that you may need to further escape the backslashes depending on your
607 When compiled with cygwin support then cygwin drive names are automatically
611 # @kbd{grub-install /dev/sda}
615 @chapter Installation
617 In order to install GRUB as your boot loader, you need to first
618 install the GRUB system and utilities under your UNIX-like operating
619 system (@pxref{Obtaining and Building GRUB}). You can do this either
620 from the source tarball, or as a package for your OS.
622 After you have done that, you need to install the boot loader on a
623 drive (floppy or hard disk) by using the utility
624 @command{grub-install} (@pxref{Invoking grub-install}) on a UNIX-like OS.
626 GRUB comes with boot images, which are normally put in the directory
627 @file{/usr/lib/grub/<cpu>-<platform>} (for BIOS-based machines
628 @file{/usr/lib/grub/i386-pc}). Hereafter, the directory where GRUB images are
629 initially placed (normally @file{/usr/lib/grub/<cpu>-<platform>}) will be
630 called the @dfn{image directory}, and the directory where the boot
631 loader needs to find them (usually @file{/boot}) will be called
632 the @dfn{boot directory}.
635 * Installing GRUB using grub-install::
636 * Making a GRUB bootable CD-ROM::
638 * BIOS installation::
642 @node Installing GRUB using grub-install
643 @section Installing GRUB using grub-install
645 For information on where GRUB should be installed on PC BIOS platforms,
646 @pxref{BIOS installation}.
648 In order to install GRUB under a UNIX-like OS (such
649 as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
650 grub-install}) as the superuser (@dfn{root}).
652 The usage is basically very simple. You only need to specify one
653 argument to the program, namely, where to install the boot loader. The
654 argument has to be either a device file (like @samp{/dev/hda}).
655 For example, under Linux the following will install GRUB into the MBR
656 of the first IDE disk:
659 # @kbd{grub-install /dev/sda}
662 Likewise, under GNU/Hurd, this has the same effect:
665 # @kbd{grub-install /dev/hd0}
668 But all the above examples assume that GRUB should put images under
669 the @file{/boot} directory. If you want GRUB to put images under a directory
670 other than @file{/boot}, you need to specify the option
671 @option{--boot-directory}. The typical usage is that you create a GRUB
672 boot floppy with a filesystem. Here is an example:
676 # @kbd{mke2fs /dev/fd0}
677 # @kbd{mount -t ext2 /dev/fd0 /mnt}
678 # @kbd{mkdir /mnt/boot}
679 # @kbd{grub-install --boot-directory=/mnt/boot /dev/fd0}
684 Some BIOSes have a bug of exposing the first partition of a USB drive as a
685 floppy instead of exposing the USB drive as a hard disk (they call it
686 ``USB-FDD'' boot). In such cases, you need to install like this:
689 # @kbd{losetup /dev/loop0 /dev/sdb1}
690 # @kbd{mount /dev/loop0 /mnt/usb}
691 # @kbd{grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0}
694 This install doesn't conflict with standard install as long as they are in
695 separate directories.
697 Note that @command{grub-install} is actually just a shell script and the
698 real task is done by other tools such as @command{grub-mkimage}. Therefore,
699 you may run those commands directly to install GRUB, without using
700 @command{grub-install}. Don't do that, however, unless you are very familiar
701 with the internals of GRUB. Installing a boot loader on a running OS may be
704 On EFI systems for fixed disk install you have to mount EFI System Partition.
705 If you mount it at @file{/boot/efi} then you don't need any special arguments:
711 Otherwise you need to specify where your EFI System partition is mounted:
714 # @kbd{grub-install --efi-directory=/mnt/efi}
717 For removable installs you have to use @option{--removable} and specify both
718 @option{--boot-directory} and @option{--efi-directory}:
721 # @kbd{grub-install --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable}
724 @node Making a GRUB bootable CD-ROM
725 @section Making a GRUB bootable CD-ROM
727 GRUB supports the @dfn{no emulation mode} in the El Torito
728 specification@footnote{El Torito is a specification for bootable CD
729 using BIOS functions.}. This means that you can use the whole CD-ROM
730 from GRUB and you don't have to make a floppy or hard disk image file,
731 which can cause compatibility problems.
733 For booting from a CD-ROM, GRUB uses a special image called
734 @file{cdboot.img}, which is concatenated with @file{core.img}. The
735 @file{core.img} used for this should be built with at least the
736 @samp{iso9660} and @samp{biosdisk} modules. Your bootable CD-ROM will
737 usually also need to include a configuration file @file{grub.cfg} and some
740 To make a simple generic GRUB rescue CD, you can use the
741 @command{grub-mkrescue} program (@pxref{Invoking grub-mkrescue}):
744 $ @kbd{grub-mkrescue -o grub.iso}
747 You will often need to include other files in your image. To do this, first
748 make a top directory for the bootable image, say, @samp{iso}:
754 Make a directory for GRUB:
757 $ @kbd{mkdir -p iso/boot/grub}
760 If desired, make the config file @file{grub.cfg} under @file{iso/boot/grub}
761 (@pxref{Configuration}), and copy any files and directories for the disc to the
762 directory @file{iso/}.
764 Finally, make the image:
767 $ @kbd{grub-mkrescue -o grub.iso iso}
770 This produces a file named @file{grub.iso}, which then can be burned
771 into a CD (or a DVD), or written to a USB mass storage device.
773 The root device will be set up appropriately on entering your
774 @file{grub.cfg} configuration file, so you can refer to file names on the CD
775 without needing to use an explicit device name. This makes it easier to
776 produce rescue images that will work on both optical drives and USB mass
781 @section The map between BIOS drives and OS devices
783 If the device map file exists, the GRUB utilities (@command{grub-probe},
784 etc.) read it to map BIOS drives to OS devices. This file consists of lines
788 (@var{device}) @var{file}
791 @var{device} is a drive specified in the GRUB syntax (@pxref{Device
792 syntax}), and @var{file} is an OS file, which is normally a device file.
794 Historically, the device map file was used because GRUB device names had to
795 be used in the configuration file, and they were derived from BIOS drive
796 numbers. The map between BIOS drives and OS devices cannot always be
797 guessed correctly: for example, GRUB will get the order wrong if you
798 exchange the boot sequence between IDE and SCSI in your BIOS.
800 Unfortunately, even OS device names are not always stable. Modern versions
801 of the Linux kernel may probe drives in a different order from boot to boot,
802 and the prefix (@file{/dev/hd*} versus @file{/dev/sd*}) may change depending
803 on the driver subsystem in use. As a result, the device map file required
804 frequent editing on some systems.
806 GRUB avoids this problem nowadays by using UUIDs or file system labels when
807 generating @file{grub.cfg}, and we advise that you do the same for any
808 custom menu entries you write. If the device map file does not exist, then
809 the GRUB utilities will assume a temporary device map on the fly. This is
810 often good enough, particularly in the common case of single-disk systems.
812 However, the device map file is not entirely obsolete yet, and it is
813 used for overriding when current environment is different from the one on boot.
814 Most common case is if you use a partition or logical volume as a disk for
815 virtual machine. You can put any comments in the file if needed,
816 as the GRUB utilities assume that a line is just a comment if
817 the first character is @samp{#}.
820 @node BIOS installation
821 @section BIOS installation
825 The partition table format traditionally used on PC BIOS platforms is called
826 the Master Boot Record (MBR) format; this is the format that allows up to
827 four primary partitions and additional logical partitions. With this
828 partition table format, there are two ways to install GRUB: it can be
829 embedded in the area between the MBR and the first partition (called by
830 various names, such as the "boot track", "MBR gap", or "embedding area", and
831 which is usually at least 31 KiB), or the core image can be installed in a
832 file system and a list of the blocks that make it up can be stored in the
833 first sector of that partition.
835 Each of these has different problems. There is no way to reserve space in
836 the embedding area with complete safety, and some proprietary software is
837 known to use it to make it difficult for users to work around licensing
838 restrictions; and systems are sometimes partitioned without leaving enough
839 space before the first partition. On the other hand, installing to a
840 filesystem means that GRUB is vulnerable to its blocks being moved around by
841 filesystem features such as tail packing, or even by aggressive fsck
842 implementations, so this approach is quite fragile; and this approach can
843 only be used if the @file{/boot} filesystem is on the same disk that the
844 BIOS boots from, so that GRUB does not have to rely on guessing BIOS drive
847 The GRUB development team generally recommends embedding GRUB before the
848 first partition, unless you have special requirements. You must ensure that
849 the first partition starts at least 31 KiB (63 sectors) from the start of
850 the disk; on modern disks, it is often a performance advantage to align
851 partitions on larger boundaries anyway, so the first partition might start 1
852 MiB from the start of the disk.
856 Some newer systems use the GUID Partition Table (GPT) format. This was
857 specified as part of the Extensible Firmware Interface (EFI), but it can
858 also be used on BIOS platforms if system software supports it; for example,
859 GRUB and GNU/Linux can be used in this configuration. With this format, it
860 is possible to reserve a whole partition for GRUB, called the BIOS Boot
861 Partition. GRUB can then be embedded into that partition without the risk
862 of being overwritten by other software and without being contained in a
863 filesystem which might move its blocks around.
865 When creating a BIOS Boot Partition on a GPT system, you should make sure
866 that it is at least 31 KiB in size. (GPT-formatted disks are not usually
867 particularly small, so we recommend that you make it larger than the bare
868 minimum, such as 1 MiB, to allow plenty of room for growth.) You must also
869 make sure that it has the proper partition type. Using GNU Parted, you can
870 set this using a command such as the following:
873 # @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
876 If you are using gdisk, set the partition type to @samp{0xEF02}. With
877 partitioning programs that require setting the GUID directly, it should be
878 @samp{21686148-6449-6e6f-744e656564454649}.
880 @strong{Caution:} Be very careful which partition you select! When GRUB
881 finds a BIOS Boot Partition during installation, it will automatically
882 overwrite part of it. Make sure that the partition does not contain any
889 GRUB can load Multiboot-compliant kernels in a consistent way,
890 but for some free operating systems you need to use some OS-specific
894 * General boot methods:: How to boot OSes with GRUB generally
895 * Loopback booting:: Notes on booting from loopbacks
896 * OS-specific notes:: Notes on some operating systems
900 @node General boot methods
901 @section How to boot operating systems
903 GRUB has two distinct boot methods. One of the two is to load an
904 operating system directly, and the other is to chain-load another boot
905 loader which then will load an operating system actually. Generally
906 speaking, the former is more desirable, because you don't need to
907 install or maintain other boot loaders and GRUB is flexible enough to
908 load an operating system from an arbitrary disk/partition. However,
909 the latter is sometimes required, since GRUB doesn't support all the
910 existing operating systems natively.
913 * Loading an operating system directly::
918 @node Loading an operating system directly
919 @subsection How to boot an OS directly with GRUB
921 Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
922 The Multiboot Specification}) is the native format supported by GRUB.
923 For the sake of convenience, there is also support for Linux, FreeBSD,
924 NetBSD and OpenBSD. If you want to boot other operating systems, you
925 will have to chain-load them (@pxref{Chain-loading}).
927 FIXME: this section is incomplete.
931 Run the command @command{boot} (@pxref{boot}).
934 However, DOS and Windows have some deficiencies, so you might have to
935 use more complicated instructions. @xref{DOS/Windows}, for more
940 @subsection Chain-loading an OS
942 Operating systems that do not support Multiboot and do not have specific
943 support in GRUB (specific support is available for Linux, FreeBSD, NetBSD
944 and OpenBSD) must be chain-loaded, which involves loading another boot
945 loader and jumping to it in real mode.
947 The @command{chainloader} command (@pxref{chainloader}) is used to set this
948 up. It is normally also necessary to load some GRUB modules and set the
949 appropriate root device. Putting this together, we get something like this,
950 for a Windows system on the first partition of the first hard disk:
953 menuentry "Windows" {
960 @c FIXME: document UUIDs.
962 On systems with multiple hard disks, an additional workaround may be
963 required. @xref{DOS/Windows}.
965 Chain-loading is only supported on PC BIOS and EFI platforms.
967 @node Loopback booting
968 @section Loopback booting
969 GRUB is able to read from an image (be it one of CD or HDD) stored on
970 any of its accessible storages (refer to @pxref{loopback} command).
971 However the OS itself should be able to find its root. This usually
972 involves running a userspace program running before the real root
973 is discovered. This is achieved by GRUB loading a specially made
974 small image and passing it as ramdisk to the kernel. This is achieved
975 by commands @command{kfreebsd_module}, @command{knetbsd_module_elf},
976 @command{kopenbsd_ramdisk}, @command{initrd} (@pxref{initrd}),
977 @command{initrd16} (@pxref{initrd}), @command{multiboot_module},
978 @command{multiboot2_module} or @command{xnu_ramdisk}
979 depending on the loader. Note that for knetbsd the image must be put
980 inside miniroot.kmod and the whole miniroot.kmod has to be loaded. In
981 kopenbsd payload this is disabled by default. Aditionally behaviour of
982 initial ramdisk depends on command line options. Several distributors provide
983 the image for this purpose or it's integrated in their standard ramdisk and
984 activated by special option. Consult your kernel and distribution manual for
985 more details. Other loaders like appleloader, chainloader (BIOS, EFI, coreboot),
986 freedos, ntldr and plan9 provide no possibility of loading initial ramdisk and
987 as far as author is aware the payloads in question don't support either initial
988 ramdisk or discovering loopback boot in other way and as such not bootable this
989 way. Please consider alternative boot methods like copying all files
990 from the image to actual partition. Consult your OS documentation for
993 @node OS-specific notes
994 @section Some caveats on OS-specific issues
996 Here, we describe some caveats on several operating systems.
1007 @subsection GNU/Hurd
1009 Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
1010 nothing special about it. But do not forget that you have to specify a
1011 root partition to the kernel.
1015 Set GRUB's root device to the same drive as GNU/Hurd's. The command
1016 @code{search --set=root --file /boot/gnumach.gz} or similar may help you
1020 Load the kernel and the modules, like this:
1024 grub> @kbd{multiboot /boot/gnumach.gz root=device:hd0s1}
1025 grub> @kbd{module /hurd/ext2fs.static ext2fs --readonly \
1026 --multiboot-command-line='$@{kernel-command-line@}' \
1027 --host-priv-port='$@{host-port@}' \
1028 --device-master-port='$@{device-port@}' \
1029 --exec-server-task='$@{exec-task@}' -T typed '$@{root@}' \
1030 '$(task-create)' '$(task-resume)'}
1031 grub> @kbd{module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)'}
1036 Finally, run the command @command{boot} (@pxref{boot}).
1041 @subsection GNU/Linux
1043 It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
1044 resembles to boot a Multiboot-compliant OS.
1048 Set GRUB's root device to the same drive as GNU/Linux's. The command
1049 @code{search --set=root --file /vmlinuz} or similar may help you
1053 Load the kernel using the command @command{linux} (@pxref{linux}):
1056 grub> @kbd{linux /vmlinuz root=/dev/sda1}
1059 If you need to specify some kernel parameters, just append them to the
1060 command. For example, to set @option{acpi} to @samp{off}, do this:
1063 grub> @kbd{linux /vmlinuz root=/dev/sda1 acpi=off}
1066 See the documentation in the Linux source tree for complete information on
1067 the available options.
1069 With @command{linux} GRUB uses 32-bit protocol. Some BIOS services like APM
1070 or EDD aren't available with this protocol. In this case you need to use
1074 grub> @kbd{linux16 /vmlinuz root=/dev/sda1 acpi=off}
1078 If you use an initrd, execute the command @command{initrd} (@pxref{initrd})
1079 after @command{linux}:
1082 grub> @kbd{initrd /initrd}
1085 If you used @command{linux16} you need to use @command{initrd16}:
1088 grub> @kbd{initrd16 /initrd}
1092 Finally, run the command @command{boot} (@pxref{boot}).
1095 @strong{Caution:} If you use an initrd and specify the @samp{mem=}
1096 option to the kernel to let it use less than actual memory size, you
1097 will also have to specify the same memory size to GRUB. To let GRUB know
1098 the size, run the command @command{uppermem} @emph{before} loading the
1099 kernel. @xref{uppermem}, for more information.
1105 Booting a NetBSD kernel from GRUB is also relatively easy: first set
1106 GRUB's root device, then load the kernel and the modules, and finally
1111 Set GRUB's root device to the partition holding the NetBSD root file
1112 system. For a disk with a NetBSD disk label, this is usually the first
1113 partition (a:). In that case, and assuming that the partition is on the
1114 first hard disk, set GRUB's root device as follows:
1117 grub> @kbd{insmod part_bsd}
1118 grub> @kbd{set root=(hd0,netbsd1)}
1121 For a disk with a GUID Partition Table (GPT), and assuming that the
1122 NetBSD root partition is the third GPT partition, do this:
1125 grub> @kbd{insmod part_gpt}
1126 grub> @kbd{set root=(hd0,gpt3)}
1130 Load the kernel using the command @command{knetbsd}:
1133 grub> @kbd{knetbsd /netbsd}
1136 Various options may be given to @command{knetbsd}. These options are,
1137 for the most part, the same as in the NetBSD boot loader. For instance,
1138 to boot the system in single-user mode and with verbose messages, do
1142 grub> @kbd{knetbsd /netbsd -s -v}
1146 If needed, load kernel modules with the command
1147 @command{knetbsd_module_elf}. A typical example is the module for the
1151 grub> @kbd{knetbsd_module_elf /stand/amd64/6.0/modules/ffs/ffs.kmod}
1155 Finally, run the command @command{boot} (@pxref{boot}).
1160 @subsection DOS/Windows
1162 GRUB cannot boot DOS or Windows directly, so you must chain-load them
1163 (@pxref{Chain-loading}). However, their boot loaders have some critical
1164 deficiencies, so it may not work to just chain-load them. To overcome
1165 the problems, GRUB provides you with two helper functions.
1167 If you have installed DOS (or Windows) on a non-first hard disk, you
1168 have to use the disk swapping technique, because that OS cannot boot
1169 from any disks but the first one. The workaround used in GRUB is the
1170 command @command{drivemap} (@pxref{drivemap}), like this:
1173 drivemap -s (hd0) (hd1)
1176 This performs a @dfn{virtual} swap between your first and second hard
1179 @strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
1180 to access the swapped disks. If that OS uses a special driver for the
1181 disks, this probably won't work.
1183 Another problem arises if you installed more than one set of DOS/Windows
1184 onto one disk, because they could be confused if there are more than one
1185 primary partitions for DOS/Windows. Certainly you should avoid doing
1186 this, but there is a solution if you do want to do so. Use the partition
1187 hiding/unhiding technique.
1189 If GRUB @dfn{hides} a DOS (or Windows) partition (@pxref{parttool}), DOS (or
1190 Windows) will ignore the partition. If GRUB @dfn{unhides} a DOS (or Windows)
1191 partition, DOS (or Windows) will detect the partition. Thus, if you have
1192 installed DOS (or Windows) on the first and the second partition of the
1193 first hard disk, and you want to boot the copy on the first partition, do
1198 parttool (hd0,1) hidden-
1199 parttool (hd0,2) hidden+
1202 parttool @verb{'${root}'} boot+
1209 @chapter Writing your own configuration file
1211 GRUB is configured using @file{grub.cfg}, usually located under
1212 @file{/boot/grub}. This file is quite flexible, but most users will not
1213 need to write the whole thing by hand.
1216 * Simple configuration:: Recommended for most users
1217 * Shell-like scripting:: For power users and developers
1218 * Multi-boot manual config:: For non-standard multi-OS scenarios
1219 * Embedded configuration:: Embedding a configuration file into GRUB
1223 @node Simple configuration
1224 @section Simple configuration handling
1226 The program @command{grub-mkconfig} (@pxref{Invoking grub-mkconfig})
1227 generates @file{grub.cfg} files suitable for most cases. It is suitable for
1228 use when upgrading a distribution, and will discover available kernels and
1229 attempt to generate menu entries for them.
1231 @command{grub-mkconfig} does have some limitations. While adding extra
1232 custom menu entries to the end of the list can be done by editing
1233 @file{/etc/grub.d/40_custom} or creating @file{/boot/grub/custom.cfg},
1234 changing the order of menu entries or changing their titles may require
1235 making complex changes to shell scripts stored in @file{/etc/grub.d/}. This
1236 may be improved in the future. In the meantime, those who feel that it
1237 would be easier to write @file{grub.cfg} directly are encouraged to do so
1238 (@pxref{Booting}, and @ref{Shell-like scripting}), and to disable any system
1239 provided by their distribution to automatically run @command{grub-mkconfig}.
1241 The file @file{/etc/default/grub} controls the operation of
1242 @command{grub-mkconfig}. It is sourced by a shell script, and so must be
1243 valid POSIX shell input; normally, it will just be a sequence of
1244 @samp{KEY=value} lines, but if the value contains spaces or other special
1245 characters then it must be quoted. For example:
1248 GRUB_TERMINAL_INPUT="console serial"
1251 Valid keys in @file{/etc/default/grub} are as follows:
1255 The default menu entry. This may be a number, in which case it identifies
1256 the Nth entry in the generated menu counted from zero, or the title of a
1257 menu entry, or the special string @samp{saved}. Using the id may be
1258 useful if you want to set a menu entry as the default even though there may
1259 be a variable number of entries before it.
1261 For example, if you have:
1264 menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux {
1269 then you can make this the default using:
1272 GRUB_DEFAULT=example-gnu-linux
1275 Previously it was documented the way to use entry title. While this still
1276 works it's not recommended since titles often contain unstable device names
1277 and may be translated
1279 If you set this to @samp{saved}, then the default menu entry will be that
1280 saved by @samp{GRUB_SAVEDEFAULT} or @command{grub-set-default}. This relies on
1281 the environment block, which may not be available in all situations
1282 (@pxref{Environment block}).
1284 The default is @samp{0}.
1286 @item GRUB_SAVEDEFAULT
1287 If this option is set to @samp{true}, then, when an entry is selected, save
1288 it as a new default entry for use by future runs of GRUB. This is only
1289 useful if @samp{GRUB_DEFAULT=saved}; it is a separate option because
1290 @samp{GRUB_DEFAULT=saved} is useful without this option, in conjunction with
1291 @command{grub-set-default}. Unset by default.
1292 This option relies on the environment block, which may not be available in
1293 all situations (@pxref{Environment block}).
1296 Boot the default entry this many seconds after the menu is displayed, unless
1297 a key is pressed. The default is @samp{5}. Set to @samp{0} to boot
1298 immediately without displaying the menu, or to @samp{-1} to wait
1301 @item GRUB_HIDDEN_TIMEOUT
1302 Wait this many seconds for @key{ESC} to be pressed before displaying the menu.
1303 If no @key{ESC} is pressed during that time, display the menu for the number of
1304 seconds specified in GRUB_TIMEOUT before booting the default entry. We expect
1305 that most people who use GRUB_HIDDEN_TIMEOUT will want to have GRUB_TIMEOUT set
1306 to @samp{0} so that the menu is not displayed at all unless @key{ESC} is
1310 @item GRUB_HIDDEN_TIMEOUT_QUIET
1311 In conjunction with @samp{GRUB_HIDDEN_TIMEOUT}, set this to @samp{true} to
1312 suppress the verbose countdown while waiting for a key to be pressed before
1313 displaying the menu. Unset by default.
1315 @item GRUB_DEFAULT_BUTTON
1316 @itemx GRUB_TIMEOUT_BUTTON
1317 @itemx GRUB_HIDDEN_TIMEOUT_BUTTON
1318 @itemx GRUB_BUTTON_CMOS_ADDRESS
1319 Variants of the corresponding variables without the @samp{_BUTTON} suffix,
1320 used to support vendor-specific power buttons. @xref{Vendor power-on keys}.
1322 @item GRUB_DISTRIBUTOR
1323 Set by distributors of GRUB to their identifying name. This is used to
1324 generate more informative menu entry titles.
1326 @item GRUB_TERMINAL_INPUT
1327 Select the terminal input device. You may select multiple devices here,
1328 separated by spaces.
1330 Valid terminal input names depend on the platform, but may include
1331 @samp{console} (native platform console), @samp{serial} (serial terminal),
1332 @samp{serial_<port>} (serial terminal with explicit port selection),
1333 @samp{at_keyboard} (PC AT keyboard), or @samp{usb_keyboard} (USB keyboard
1334 using the HID Boot Protocol, for cases where the firmware does not handle
1337 The default is to use the platform's native terminal input.
1339 @item GRUB_TERMINAL_OUTPUT
1340 Select the terminal output device. You may select multiple devices here,
1341 separated by spaces.
1343 Valid terminal output names depend on the platform, but may include
1344 @samp{console} (native platform console), @samp{serial} (serial terminal),
1345 @samp{serial_<port>} (serial terminal with explicit port selection),
1346 @samp{gfxterm} (graphics-mode output), @samp{vga_text} (VGA text output),
1347 @samp{mda_text} (MDA text output), @samp{morse} (Morse-coding using system
1348 beeper) or @samp{spkmodem} (simple data protocol using system speaker).
1350 @samp{spkmodem} is useful when no serial port is available. Connect the output
1351 of sending system (where GRUB is running) to line-in of receiving system
1352 (usually developer machine).
1353 On receiving system compile @samp{spkmodem-recv} from
1354 @samp{util/spkmodem-recv.c} and run:
1357 parecord --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv
1360 The default is to use the platform's native terminal output.
1363 If this option is set, it overrides both @samp{GRUB_TERMINAL_INPUT} and
1364 @samp{GRUB_TERMINAL_OUTPUT} to the same value.
1366 @item GRUB_SERIAL_COMMAND
1367 A command to configure the serial port when using the serial console.
1368 @xref{serial}. Defaults to @samp{serial}.
1370 @item GRUB_CMDLINE_LINUX
1371 Command-line arguments to add to menu entries for the Linux kernel.
1373 @item GRUB_CMDLINE_LINUX_DEFAULT
1374 Unless @samp{GRUB_DISABLE_RECOVERY} is set to @samp{true}, two menu
1375 entries will be generated for each Linux kernel: one default entry and one
1376 entry for recovery mode. This option lists command-line arguments to add
1377 only to the default menu entry, after those listed in
1378 @samp{GRUB_CMDLINE_LINUX}.
1380 @item GRUB_CMDLINE_NETBSD
1381 @itemx GRUB_CMDLINE_NETBSD_DEFAULT
1382 As @samp{GRUB_CMDLINE_LINUX} and @samp{GRUB_CMDLINE_LINUX_DEFAULT}, but for
1385 @item GRUB_CMDLINE_GNUMACH
1386 As @samp{GRUB_CMDLINE_LINUX}, but for GNU Mach.
1388 @item GRUB_CMDLINE_XEN
1389 @itemx GRUB_CMDLINE_XEN_DEFAULT
1390 The values of these options are passed to Xen hypervisor Xen menu entries,
1391 for all respectively normal entries.
1393 @item GRUB_CMDLINE_LINUX_XEN_REPLACE
1394 @item GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT
1395 The values of these options replace the values of @samp{GRUB_CMDLINE_LINUX}
1396 and @samp{GRUB_CMDLINE_LINUX_DEFAULT} for Linux and Xen menu entries.
1398 @item GRUB_DISABLE_LINUX_UUID
1399 Normally, @command{grub-mkconfig} will generate menu entries that use
1400 universally-unique identifiers (UUIDs) to identify the root filesystem to
1401 the Linux kernel, using a @samp{root=UUID=...} kernel parameter. This is
1402 usually more reliable, but in some cases it may not be appropriate. To
1403 disable the use of UUIDs, set this option to @samp{true}.
1405 @item GRUB_DISABLE_RECOVERY
1406 If this option is set to @samp{true}, disable the generation of recovery
1409 @item GRUB_VIDEO_BACKEND
1410 If graphical video support is required, either because the @samp{gfxterm}
1411 graphical terminal is in use or because @samp{GRUB_GFXPAYLOAD_LINUX} is set,
1412 then @command{grub-mkconfig} will normally load all available GRUB video
1413 drivers and use the one most appropriate for your hardware. If you need to
1414 override this for some reason, then you can set this option.
1416 After @command{grub-install} has been run, the available video drivers are
1417 listed in @file{/boot/grub/video.lst}.
1420 Set the resolution used on the @samp{gfxterm} graphical terminal. Note that
1421 you can only use modes which your graphics card supports via VESA BIOS
1422 Extensions (VBE), so for example native LCD panel resolutions may not be
1423 available. The default is @samp{auto}, which tries to select a preferred
1424 resolution. @xref{gfxmode}.
1426 @item GRUB_BACKGROUND
1427 Set a background image for use with the @samp{gfxterm} graphical terminal.
1428 The value of this option must be a file readable by GRUB at boot time, and
1429 it must end with @file{.png}, @file{.tga}, @file{.jpg}, or @file{.jpeg}.
1430 The image will be scaled if necessary to fit the screen.
1433 Set a theme for use with the @samp{gfxterm} graphical terminal.
1435 @item GRUB_GFXPAYLOAD_LINUX
1436 Set to @samp{text} to force the Linux kernel to boot in normal text mode,
1437 @samp{keep} to preserve the graphics mode set using @samp{GRUB_GFXMODE},
1438 @samp{@var{width}x@var{height}}[@samp{x@var{depth}}] to set a particular
1439 graphics mode, or a sequence of these separated by commas or semicolons to
1440 try several modes in sequence. @xref{gfxpayload}.
1442 Depending on your kernel, your distribution, your graphics card, and the
1443 phase of the moon, note that using this option may cause GNU/Linux to suffer
1444 from various display problems, particularly during the early part of the
1445 boot sequence. If you have problems, set this option to @samp{text} and
1446 GRUB will tell Linux to boot in normal text mode.
1448 @item GRUB_DISABLE_OS_PROBER
1449 Normally, @command{grub-mkconfig} will try to use the external
1450 @command{os-prober} program, if installed, to discover other operating
1451 systems installed on the same system and generate appropriate menu entries
1452 for them. Set this option to @samp{true} to disable this.
1454 @item GRUB_OS_PROBER_SKIP_LIST
1455 List of space-separated FS UUIDs of filesystems to be ignored from os-prober
1456 output. For efi chainloaders it's <UUID>@@<EFI FILE>
1458 @item GRUB_DISABLE_SUBMENU
1459 Normally, @command{grub-mkconfig} will generate top level menu entry for
1460 the kernel with highest version number and put all other found kernels
1461 or alternative menu entries for recovery mode in submenu. For entries returned
1462 by @command{os-prober} first entry will be put on top level and all others
1463 in submenu. If this option is set to @samp{y}, flat menu with all entries
1464 on top level will be generated instead. Changing this option will require
1465 changing existing values of @samp{GRUB_DEFAULT}, @samp{fallback} (@pxref{fallback})
1466 and @samp{default} (@pxref{default}) environment variables as well as saved
1467 default entry using @command{grub-set-default} and value used with
1468 @command{grub-reboot}.
1470 @item GRUB_ENABLE_CRYPTODISK
1471 If set to @samp{y}, @command{grub-mkconfig} and @command{grub-install} will
1472 check for encrypted disks and generate additional commands needed to access
1473 them during boot. Note that in this case unattended boot is not possible
1474 because GRUB will wait for passphrase to unlock encrypted container.
1476 @item GRUB_INIT_TUNE
1477 Play a tune on the speaker when GRUB starts. This is particularly useful
1478 for users unable to see the screen. The value of this option is passed
1479 directly to @ref{play}.
1482 If this option is set, GRUB will issue a @ref{badram} command to filter
1483 out specified regions of RAM.
1485 @item GRUB_PRELOAD_MODULES
1486 This option may be set to a list of GRUB module names separated by spaces.
1487 Each module will be loaded as early as possible, at the start of
1492 For more detailed customisation of @command{grub-mkconfig}'s output, you may
1493 edit the scripts in @file{/etc/grub.d} directly.
1494 @file{/etc/grub.d/40_custom} is particularly useful for adding entire custom
1495 menu entries; simply type the menu entries you want to add at the end of
1496 that file, making sure to leave at least the first two lines intact.
1499 @node Shell-like scripting
1500 @section Writing full configuration files directly
1502 @c Some of this section is derived from the GNU Bash manual page, also
1503 @c copyrighted by the FSF.
1505 @file{grub.cfg} is written in GRUB's built-in scripting language, which has
1506 a syntax quite similar to that of GNU Bash and other Bourne shell
1511 A @dfn{word} is a sequence of characters considered as a single unit by
1512 GRUB. Words are separated by @dfn{metacharacters}, which are the following
1513 plus space, tab, and newline:
1519 Quoting may be used to include metacharacters in words; see below.
1521 @heading Reserved words
1523 Reserved words have a special meaning to GRUB. The following words are
1524 recognised as reserved when unquoted and either the first word of a simple
1525 command or the third word of a @code{for} command:
1529 case do done elif else esac fi for function
1530 if in menuentry select then time until while
1533 Not all of these reserved words have a useful purpose yet; some are reserved
1534 for future expansion.
1538 Quoting is used to remove the special meaning of certain characters or
1539 words. It can be used to treat metacharacters as part of a word, to prevent
1540 reserved words from being recognised as such, and to prevent variable
1543 There are three quoting mechanisms: the escape character, single quotes, and
1546 A non-quoted backslash (\) is the @dfn{escape character}. It preserves the
1547 literal value of the next character that follows, with the exception of
1550 Enclosing characters in single quotes preserves the literal value of each
1551 character within the quotes. A single quote may not occur between single
1552 quotes, even when preceded by a backslash.
1554 Enclosing characters in double quotes preserves the literal value of all
1555 characters within the quotes, with the exception of @samp{$} and @samp{\}.
1556 The @samp{$} character retains its special meaning within double quotes.
1557 The backslash retains its special meaning only when followed by one of the
1558 following characters: @samp{$}, @samp{"}, @samp{\}, or newline. A
1559 backslash-newline pair is treated as a line continuation (that is, it is
1560 removed from the input stream and effectively ignored@footnote{Currently a
1561 backslash-newline pair within a variable name is not handled properly, so
1562 use this feature with some care.}). A double quote may be quoted within
1563 double quotes by preceding it with a backslash.
1565 @heading Variable expansion
1567 The @samp{$} character introduces variable expansion. The variable name to
1568 be expanded may be enclosed in braces, which are optional but serve to
1569 protect the variable to be expanded from characters immediately following it
1570 which could be interpreted as part of the name.
1572 Normal variable names begin with an alphabetic character, followed by zero
1573 or more alphanumeric characters. These names refer to entries in the GRUB
1574 environment (@pxref{Environment}).
1576 Positional variable names consist of one or more digits. They represent
1577 parameters passed to function calls, with @samp{$1} representing the first
1578 parameter, and so on.
1580 The special variable name @samp{?} expands to the exit status of the most
1581 recently executed command. When positional variable names are active, other
1582 special variable names @samp{@@}, @samp{*} and @samp{#} are defined and they
1583 expand to all positional parameters with necessary quoting, positional
1584 parameters without any quoting, and positional parameter count respectively.
1588 A word beginning with @samp{#} causes that word and all remaining characters
1589 on that line to be ignored.
1591 @heading Simple commands
1593 A @dfn{simple command} is a sequence of words separated by spaces or tabs
1594 and terminated by a semicolon or a newline. The first word specifies the
1595 command to be executed. The remaining words are passed as arguments to the
1598 The return value of a simple command is its exit status. If the reserved
1599 word @code{!} precedes the command, then the return value is instead the
1600 logical negation of the command's exit status.
1602 @heading Compound commands
1604 A @dfn{compound command} is one of the following:
1607 @item for @var{name} in @var{word} @dots{}; do @var{list}; done
1608 The list of words following @code{in} is expanded, generating a list of
1609 items. The variable @var{name} is set to each element of this list in turn,
1610 and @var{list} is executed each time. The return value is the exit status
1611 of the last command that executes. If the expansion of the items following
1612 @code{in} results in an empty list, no commands are executed, and the return
1615 @item if @var{list}; then @var{list}; [elif @var{list}; then @var{list};] @dots{} [else @var{list};] fi
1616 The @code{if} @var{list} is executed. If its exit status is zero, the
1617 @code{then} @var{list} is executed. Otherwise, each @code{elif} @var{list}
1618 is executed in turn, and if its exit status is zero, the corresponding
1619 @code{then} @var{list} is executed and the command completes. Otherwise,
1620 the @code{else} @var{list} is executed, if present. The exit status is the
1621 exit status of the last command executed, or zero if no condition tested
1624 @item while @var{cond}; do @var{list}; done
1625 @itemx until @var{cond}; do @var{list}; done
1626 The @code{while} command continuously executes the @code{do} @var{list} as
1627 long as the last command in @var{cond} returns an exit status of zero. The
1628 @code{until} command is identical to the @code{while} command, except that
1629 the test is negated; the @code{do} @var{list} is executed as long as the
1630 last command in @var{cond} returns a non-zero exit status. The exit status
1631 of the @code{while} and @code{until} commands is the exit status of the last
1632 @code{do} @var{list} command executed, or zero if none was executed.
1634 @item function @var{name} @{ @var{command}; @dots{} @}
1635 This defines a function named @var{name}. The @dfn{body} of the function is
1636 the list of commands within braces, each of which must be terminated with a
1637 semicolon or a newline. This list of commands will be executed whenever
1638 @var{name} is specified as the name of a simple command. Function
1639 definitions do not affect the exit status in @code{$?}. When executed, the
1640 exit status of a function is the exit status of the last command executed in
1643 @item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @{ @var{command}; @dots{} @}
1647 @heading Built-in Commands
1649 Some built-in commands are also provided by GRUB script to help script
1650 writers perform actions that are otherwise not possible. For example, these
1651 include commands to jump out of a loop without fully completing it, etc.
1654 @item break [@code{n}]
1655 Exit from within a @code{for}, @code{while}, or @code{until} loop. If
1656 @code{n} is specified, break @code{n} levels. @code{n} must be greater than
1657 or equal to 1. If @code{n} is greater than the number of enclosing loops,
1658 all enclosing loops are exited. The return value is 0 unless @code{n} is
1659 not greater than or equal to 1.
1661 @item continue [@code{n}]
1662 Resume the next iteration of the enclosing @code{for}, @code{while} or
1663 @code{until} loop. If @code{n} is specified, resume at the @code{n}th
1664 enclosing loop. @code{n} must be greater than or equal to 1. If @code{n}
1665 is greater than the number of enclosing loops, the last enclosing loop (the
1666 @dfn{top-level} loop) is resumed. The return value is 0 unless @code{n} is
1667 not greater than or equal to 1.
1669 @item return [@code{n}]
1670 Causes a function to exit with the return value specified by @code{n}. If
1671 @code{n} is omitted, the return status is that of the last command executed
1672 in the function body. If used outside a function the return status is
1675 @item setparams [@code{arg}] @dots{}
1676 Replace positional parameters starting with @code{$1} with arguments to
1677 @command{setparams}.
1679 @item shift [@code{n}]
1680 The positional parameters from @code{n}+1 @dots{} are renamed to
1681 @code{$1}@dots{}. Parameters represented by the numbers @code{$#} down to
1682 @code{$#}-@code{n}+1 are unset. @code{n} must be a non-negative number less
1683 than or equal to @code{$#}. If @code{n} is 0, no parameters are changed.
1684 If @code{n} is not given, it is assumed to be 1. If @code{n} is greater
1685 than @code{$#}, the positional parameters are not changed. The return
1686 status is greater than zero if @code{n} is greater than @code{$#} or less
1687 than zero; otherwise 0.
1691 @node Multi-boot manual config
1692 @section Multi-boot manual config
1694 Currently autogenerating config files for multi-boot environments depends on
1695 os-prober and has several shortcomings. While fixing it is scheduled for the
1696 next release, meanwhile you can make use of the power of GRUB syntax and do it
1697 yourself. A possible configuration is detailed here, feel free to adjust to your
1700 First create a separate GRUB partition, big enough to hold GRUB. Some of the
1701 following entries show how to load OS installer images from this same partition,
1702 for that you obviously need to make the partition large enough to hold those
1704 Mount this partition on/mnt/boot and disable GRUB in all OSes and manually
1705 install self-compiled latest GRUB with:
1707 @code{grub-install --boot-directory=/mnt/boot /dev/sda}
1709 In all the OSes install GRUB tools but disable installing GRUB in bootsector,
1710 so you'll have menu.lst and grub.cfg available for use. Also disable os-prober
1713 @code{GRUB_DISABLE_OS_PROBER=true}
1715 in /etc/default/grub
1717 Then write a grub.cfg (/mnt/boot/grub/grub.cfg):
1721 menuentry "OS using grub2" @{
1723 search --set=root --label OS1 --hint hd0,msdos8
1724 configfile /boot/grub/grub.cfg
1727 menuentry "OS using grub2-legacy" @{
1729 search --set=root --label OS2 --hint hd0,msdos6
1730 legacy_configfile /boot/grub/menu.lst
1733 menuentry "Windows XP" @{
1735 search --set=root --label WINDOWS_XP --hint hd0,msdos1
1739 menuentry "Windows 7" @{
1741 search --set=root --label WINDOWS_7 --hint hd0,msdos2
1745 menuentry "FreeBSD" @{
1747 search --set=root --label freepool --hint hd0,msdos7
1748 kfreebsd /freebsd@@/boot/kernel/kernel
1749 kfreebsd_module_elf /freebsd@@/boot/kernel/opensolaris.ko
1750 kfreebsd_module_elf /freebsd@@/boot/kernel/zfs.ko
1751 kfreebsd_module /freebsd@@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache
1752 set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd
1753 set kFreeBSD.hw.psm.synaptics_support=1
1756 menuentry "experimental GRUB" @{
1757 search --set=root --label GRUB --hint hd0,msdos5
1758 multiboot /experimental/grub/i386-pc/core.img
1761 menuentry "Fedora 16 installer" @{
1762 search --set=root --label GRUB --hint hd0,msdos5
1763 linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280x800
1764 initrd /fedora/initrd.img
1767 menuentry "Fedora rawhide installer" @{
1768 search --set=root --label GRUB --hint hd0,msdos5
1769 linux /fedora/vmlinuz repo=ftp://mirror.switch.ch/mirror/fedora/linux/development/rawhide/x86_64 lang=en_US keymap=sg resolution=1280x800
1770 initrd /fedora/initrd.img
1773 menuentry "Debian sid installer" @{
1774 search --set=root --label GRUB --hint hd0,msdos5
1775 linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz
1776 initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd.gz
1783 @item Argument to search after --label is FS LABEL. You can also use UUIDs with --fs-uuid UUID instead of --label LABEL. You could also use direct @code{root=hd0,msdosX} but this is not recommended due to device name instability.
1786 @node Embedded configuration
1787 @section Embedding a configuration file into GRUB
1789 GRUB supports embedding a configuration file directly into the core image,
1790 so that it is loaded before entering normal mode. This is useful, for
1791 example, when it is not straightforward to find the real configuration file,
1792 or when you need to debug problems with loading that file.
1793 @command{grub-install} uses this feature when it is not using BIOS disk
1794 functions or when installing to a different disk from the one containing
1795 @file{/boot/grub}, in which case it needs to use the @command{search}
1796 command (@pxref{search}) to find @file{/boot/grub}.
1798 To embed a configuration file, use the @option{-c} option to
1799 @command{grub-mkimage}. The file is copied into the core image, so it may
1800 reside anywhere on the file system, and may be removed after running
1801 @command{grub-mkimage}.
1803 After the embedded configuration file (if any) is executed, GRUB will load
1804 the @samp{normal} module (@pxref{normal}), which will then read the real
1805 configuration file from @file{$prefix/grub.cfg}. By this point, the
1806 @code{root} variable will also have been set to the root device name. For
1807 example, @code{prefix} might be set to @samp{(hd0,1)/boot/grub}, and
1808 @code{root} might be set to @samp{hd0,1}. Thus, in most cases, the embedded
1809 configuration file only needs to set the @code{prefix} and @code{root}
1810 variables, and then drop through to GRUB's normal processing. A typical
1811 example of this might look like this:
1815 search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root
1816 set prefix=($root)/boot/grub
1820 (The @samp{search_fs_uuid} module must be included in the core image for this
1823 In more complex cases, it may be useful to read other configuration files
1824 directly from the embedded configuration file. This allows such things as
1825 reading files not called @file{grub.cfg}, or reading files from a directory
1826 other than that where GRUB's loadable modules are installed. To do this,
1827 include the @samp{configfile} and @samp{normal} modules in the core image,
1828 and embed a configuration file that uses the @command{configfile} command to
1829 load another file. The following example of this also requires the
1830 @command{echo}, @command{search_label}, and @command{test} modules to be
1831 included in the core image:
1835 search.fs_label grub root
1836 if [ -e /boot/grub/example/test1.cfg ]; then
1837 set prefix=($root)/boot/grub
1838 configfile /boot/grub/example/test1.cfg
1840 if [ -e /boot/grub/example/test2.cfg ]; then
1841 set prefix=($root)/boot/grub
1842 configfile /boot/grub/example/test2.cfg
1844 echo "Could not find an example configuration file!"
1850 The embedded configuration file may not contain menu entries directly, but
1851 may only read them from elsewhere using @command{configfile}.
1853 @node Theme file format
1854 @chapter Theme file format
1855 @section Introduction
1856 The GRUB graphical menu supports themes that can customize the layout and
1857 appearance of the GRUB boot menu. The theme is configured through a plain
1858 text file that specifies the layout of the various GUI components (including
1859 the boot menu, timeout progress bar, and text messages) as well as the
1860 appearance using colors, fonts, and images. Example is available in docs/example_theme.txt
1862 @section Theme Elements
1865 Colors can be specified in several ways:
1868 @item HTML-style ``#RRGGBB'' or ``#RGB'' format, where *R*, *G*, and *B* are hexadecimal digits (e.g., ``#8899FF'')
1869 @item as comma-separated decimal RGB values (e.g., ``128, 128, 255'')
1870 @item with ``SVG 1.0 color names'' (e.g., ``cornflowerblue'') which must be specified in lowercase.
1873 The fonts GRUB uses ``PFF2 font format'' bitmap fonts. Fonts are specified
1874 with full font names. Currently there is no
1875 provision for a preference list of fonts, or deriving one font from another.
1876 Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}). To see the list of
1877 loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}). If there are too many fonts to
1878 fit on screen, do ``set pager=1'' before executing ``lsfonts''.
1881 @subsection Progress Bar
1883 @float Figure, Pixmap-styled progress bar
1884 @c @image{Theme_progress_bar,,,,png}
1887 @float Figure, Plain progress bar, drawn with solid color.
1888 @c @image{Theme_progress_bar_filled,,,,png}
1891 Progress bars are used to display the remaining time before GRUB boots the
1892 default menu entry. To create a progress bar that will display the remaining
1893 time before automatic boot, simply create a ``progress_bar'' component with
1894 the id ``__timeout__''. This indicates to GRUB that the progress bar should
1895 be updated as time passes, and it should be made invisible if the countdown to
1896 automatic boot is interrupted by the user.
1898 Progress bars may optionally have text displayed on them. This text is
1899 controlled by variable ``text'' which contains a printf template with the
1900 only argument %d is the number of seconds remaining. Additionally special
1901 values ``@@TIMEOUT_NOTIFICATION_SHORT@@'', ``@@TIMEOUT_NOTIFICATION_MIDDLE@@'',
1902 ``@@TIMEOUT_NOTIFICATION_LONG@@'' are replaced with standard and translated
1905 @subsection Circular Progress Indicator
1907 @c @image{Theme_circular_progress,,,,.png}
1909 The circular progress indicator functions similarly to the progress bar. When
1910 given an id of ``__timeout__'', GRUB updates the circular progress indicator's
1911 value to indicate the time remaining. For the circular progress indicator,
1912 there are two images used to render it: the *center* image, and the *tick*
1913 image. The center image is rendered in the center of the component, while the
1914 tick image is used to render each mark along the circumference of the
1920 Text labels can be placed on the boot screen. The font, color, and horizontal
1921 alignment can be specified for labels. If a label is given the id
1922 ``__timeout__'', then the ``text'' property for that label is also updated
1923 with a message informing the user of the number of seconds remaining until
1924 automatic boot. This is useful in case you want the text displayed somewhere
1925 else instead of directly on the progress bar.
1928 @subsection Boot Menu
1930 @c @image{Theme_boot_menu,,,,.png}
1932 The boot menu where GRUB displays the menu entries from the ``grub.cfg'' file.
1933 It is a list of items, where each item has a title and an optional icon. The
1934 icon is selected based on the *classes* specified for the menu entry. If
1935 there is a PNG file named ``myclass.png'' in the ``grub/themes/icons''
1936 directory, it will be displayed for items which have the class *myclass*. The
1937 boot menu can be customized in several ways, such as the font and color used
1938 for the menu entry title, and by specifying styled boxes for the menu itself
1939 and for the selected item highlight.
1942 @subsection Styled Boxes
1944 One of the most important features for customizing the layout is the use of
1945 *styled boxes*. A styled box is composed of 9 rectangular (and potentially
1946 empty) regions, which are used to seamlessly draw the styled box on screen:
1948 @multitable @columnfractions 0.3 0.3 0.3
1949 @item Northwest (nw) @tab North (n) @tab Northeast (ne)
1950 @item West (w) @tab Center (c) @tab East (e)
1951 @item Southwest (sw) @tab South (s) @tab Southeast (se)
1954 To support any size of box on screen, the center slice and the slices for the
1955 top, bottom, and sides are all scaled to the correct size for the component on
1956 screen, using the following rules:
1959 @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.
1960 @item The corner slices (northwest, northeast, southeast, and southwest) are not scaled.
1961 @item The center slice is scaled to fill the remaining space in the middle.
1964 As an example of how an image might be sliced up, consider the styled box
1965 used for a terminal view.
1967 @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.
1968 @c @image{Box_slice_example_terminal,,,,.png}
1971 @subsection Creating Styled Box Images
1973 The Inkscape_ scalable vector graphics editor is a very useful tool for
1974 creating styled box images. One process that works well for slicing a drawing
1975 into the necessary image slices is:
1978 @item Create or open the drawing you'd like use.
1979 @item Create a new layer on the top of the layer stack. Make it visible. Select this layer as the current layer.
1980 @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.
1981 @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.
1982 @item Save the drawing.
1983 @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.
1984 @item Click the layer hide icon for the slice layer in the layer palette. The rectangles will remain selected, even though they are hidden.
1985 @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.
1988 @section Theme File Manual
1990 The theme file is a plain text file. Lines that begin with ``#`` are ignored
1991 and considered comments. (Note: This may not be the case if the previous line
1992 ended where a value was expected.)
1994 The theme file contains two types of statements:
1996 @item Global properties.
1997 @item Component construction.
2000 @subsection Global Properties
2004 Global properties are specified with the simple format:
2007 @item name2: "value which may contain spaces"
2011 In this example, name3 is assigned a color value.
2014 @subsection Global Property List
2016 @multitable @columnfractions 0.3 0.6
2018 @tab Specifies the text to display at the top center of the screen as a title.
2020 @tab Defines the font used for the title message at the top of the screen.
2022 @tab Defines the color of the title message.
2024 @tab Currently unused. Left for backward compatibility.
2026 @tab Currently unused. Left for backward compatibility.
2027 @item message-bg-color
2028 @tab Currently unused. Left for backward compatibility.
2030 @tab Specifies the image to use as the background. It will be scaled
2031 to fit the screen size or proportionally scaled depending on the scale
2033 @item desktop-image-scale-method
2034 @tab Specifies the scaling method for the *desktop-image*. Options are
2035 ``stretch``, ``crop``, ``padding``, ``fitwidth``, ``fitheight``.
2036 ``stretch`` for fitting the screen size. Otherwise it is proportional
2037 scaling of a part of *desktop-image* to the part of the screen.
2038 ``crop`` part of the *desktop-image* will be proportionally scaled to
2039 fit the screen sizes. ``padding`` the entire *desktop-image* will be
2040 contained on the screen. ``fitwidth`` for fitting the *desktop-image*'s
2041 width with screen width. ``fitheight`` for fitting the *desktop-image*'s
2042 height with the screen height. Default is ``stretch``.
2043 @item desktop-image-h-align
2044 @tab Specifies the horizontal alignment of the *desktop-image* if
2045 *desktop-image-scale-method* isn't equeal to ``stretch``. Options are
2046 ``left``, ``center``, ``right``. Default is ``center``.
2047 @item desktop-image-v-align
2048 @tab Specifies the vertical alignment of the *desktop-image* if
2049 *desktop-image-scale-method* isn't equeal to ``stretch``. Options are
2050 ``top``, ``center``, ``bottom``. Default is ``center``.
2052 @tab Specifies the color for the background if *desktop-image* is not
2055 @tab Specifies the file name pattern for the styled box slices used for the
2056 command line terminal window. For example, ``terminal-box: terminal_*.png``
2057 will use the images ``terminal_c.png`` as the center area, ``terminal_n.png``
2058 as the north (top) edge, ``terminal_nw.png`` as the northwest (upper left)
2059 corner, and so on. If the image for any slice is not found, it will simply
2061 @item terminal-border
2062 @tab Specifies the border width of the terminal window.
2064 @tab Specifies the left coordinate of the terminal window.
2066 @tab Specifies the top coordinate of the terminal window.
2067 @item terminal-width
2068 @tab Specifies the width of the terminal window.
2069 @item terminal-height
2070 @tab Specifies the height of the terminal window.
2074 @subsection Component Construction
2076 Greater customizability comes is provided by components. A tree of components
2077 forms the user interface. *Containers* are components that can contain other
2078 components, and there is always a single root component which is an instance
2079 of a *canvas* container.
2081 Components are created in the theme file by prefixing the type of component
2084 @code{ + label @{ text="GRUB" font="aqui 11" color="#8FF" @} }
2086 properties of a component are specified as "name = value" (whitespace
2087 surrounding tokens is optional and is ignored) where *value* may be:
2089 @item a single word (e.g., ``align = center``, ``color = #FF8080``),
2090 @item a quoted string (e.g., ``text = "Hello, World!"``), or
2091 @item a tuple (e.g., ``preferred_size = (120, 80)``).
2094 @subsection Component List
2096 The following is a list of the components and the properties they support.
2100 A label displays a line of text.
2103 @multitable @columnfractions 0.2 0.7
2105 @tab Set to ``__timeout__`` to display the time elapsed to an automatical
2106 boot of the default entry.
2108 @tab The text to display. If ``id`` is set to ``__timeout__`` and no
2109 ``text`` property is set then the amount of seconds will be shown.
2110 If set to ``@@KEYMAP_SHORT@@``, ``@@KEYMAP_MIDDLE@@`` or
2111 ``@@KEYMAP_LONG@@`` then predefined hotkey information will be shown.
2113 @tab The font to use for text display.
2115 @tab The color of the text.
2117 @tab The horizontal alignment of the text within the component.
2118 Options are ``left``, ``center`` and ``right``.
2120 @tab Set to ``false`` to hide the label.
2124 A component that displays an image. The image is scaled to fit
2129 @multitable @columnfractions 0.2 0.7
2131 @tab The full path to the image file to load.
2135 Displays a horizontally oriented progress bar. It can be rendered using
2136 simple solid filled rectangles, or using a pair of pixmap styled boxes.
2140 @multitable @columnfractions 0.2 0.7
2142 @tab Set to ``__timeout__`` to display the time elapsed to an automatical
2143 boot of the default entry.
2145 @tab The foreground color for plain solid color rendering.
2147 @tab The background color for plain solid color rendering.
2149 @tab The border color for plain solid color rendering.
2151 @tab The text color.
2153 @tab The styled box specification for the frame of the progress bar.
2154 Example: ``progress_frame_*.png``
2155 If the value is equal to ``highlight_style`` then no styled boxes
2157 @item highlight_style
2158 @tab The styled box specification for the highlighted region of the
2159 progress bar. This box will be used to paint just the highlighted region
2160 of the bar, and will be increased in size as the bar nears completion.
2161 Example: ``progress_hl_*.png``.
2162 If the value is equal to ``bar_style`` then no styled boxes
2164 @item highlight_overlay
2165 @tab If this option is set to ``true`` then the highlight box
2166 side slices (every slice except the center slice) will overlay the
2167 frame box side slices. And the center slice of the highlight box
2168 can move all the way (from top to bottom), being drawn on the center
2169 slice of the frame box. That way we can make a progress bar with
2170 round-shaped edges so there won't be a free space from the highlight to
2171 the frame in top and bottom scrollbar positions. Default is ``false``.
2173 @tab The font to use for progress bar.
2175 @tab The text to display on the progress bar. If the progress bar's ID
2176 is set to ``__timeout__`` and the value of this property is set to
2177 ``@@TIMEOUT_NOTIFICATION_SHORT@@``, ``@@TIMEOUT_NOTIFICATION_MIDDLE@@``
2178 or ``@@TIMEOUT_NOTIFICATION_LONG@@``, then GRUB will update this
2179 property with an informative message as the timeout approaches.
2182 @item circular_progress
2183 Displays a circular progress indicator. The appearance of this component
2184 is determined by two images: the *center* image and the *tick* image. The
2185 center image is generally larger and will be drawn in the center of the
2186 component. Around the circumference of a circle within the component, the
2187 tick image will be drawn a certain number of times, depending on the
2188 properties of the component.
2192 @multitable @columnfractions 0.3 0.6
2194 @tab Set to ``__timeout__`` to display the time elapsed to an automatical
2195 boot of the default entry.
2197 @tab The file name of the image to draw in the center of the component.
2199 @tab The file name of the image to draw for the tick marks.
2201 @tab The number of ticks that make up a full circle.
2202 @item ticks_disappear
2203 @tab Boolean value indicating whether tick marks should progressively appear,
2204 or progressively disappear as *value* approaches *end*. Specify
2205 ``true`` or ``false``. Default is ``false``.
2207 @tab The position of the first tick mark to appear or disappear.
2208 Measured in "parrots", 1 "parrot" = 1 / 256 of the full circle.
2209 Use values ``xxx deg`` or ``xxx \xc2\xb0`` to set the angle in degrees.
2213 Displays the GRUB boot menu. It allows selecting items and executing them.
2217 @multitable @columnfractions 0.4 0.5
2219 @tab The font to use for the menu item titles.
2220 @item selected_item_font
2221 @tab The font to use for the selected menu item, or ``inherit`` (the default)
2222 to use ``item_font`` for the selected menu item as well.
2224 @tab The color to use for the menu item titles.
2225 @item selected_item_color
2226 @tab The color to use for the selected menu item, or ``inherit`` (the default)
2227 to use ``item_color`` for the selected menu item as well.
2229 @tab The width of menu item icons. Icons are scaled to the specified size.
2231 @tab The height of menu item icons.
2233 @tab The height of each menu item in pixels.
2235 @tab The amount of space in pixels to leave on each side of the menu item
2237 @item item_icon_space
2238 @tab The space between an item's icon and the title text, in pixels.
2240 @tab The amount of space to leave between menu items, in pixels.
2241 @item menu_pixmap_style
2242 @tab The image file pattern for the menu frame styled box.
2243 Example: ``menu_*.png`` (this will use images such as ``menu_c.png``,
2244 ``menu_w.png``, `menu_nw.png``, etc.)
2245 @item item_pixmap_style
2246 @tab The image file pattern for the item styled box.
2247 @item selected_item_pixmap_style
2248 @tab The image file pattern for the selected item highlight styled box.
2250 @tab Boolean value indicating whether the scroll bar should be drawn if the
2251 frame and thumb styled boxes are configured.
2252 @item scrollbar_frame
2253 @tab The image file pattern for the entire scroll bar.
2254 Example: ``scrollbar_*.png``
2255 @item scrollbar_thumb
2256 @tab The image file pattern for the scroll bar thumb (the part of the scroll
2257 bar that moves as scrolling occurs).
2258 Example: ``scrollbar_thumb_*.png``
2259 @item scrollbar_thumb_overlay
2260 @tab If this option is set to ``true`` then the scrollbar thumb
2261 side slices (every slice except the center slice) will overlay the
2262 scrollbar frame side slices. And the center slice of the scrollbar_thumb
2263 can move all the way (from top to bottom), being drawn on the center
2264 slice of the scrollbar frame. That way we can make a scrollbar with
2265 round-shaped edges so there won't be a free space from the thumb to
2266 the frame in top and bottom scrollbar positions. Default is ``false``.
2267 @item scrollbar_slice
2268 @tab The menu frame styled box's slice in which the scrollbar will be
2269 drawn. Possible values are ``west``, ``center``, ``east`` (default).
2270 ``west`` - the scrollbar will be drawn in the west slice (right-aligned).
2271 ``east`` - the scrollbar will be drawn in the east slice (left-aligned).
2272 ``center`` - the scrollbar will be drawn in the center slice.
2273 Note: in case of ``center`` slice:
2274 a) If the scrollbar should be drawn then boot menu entry's width is
2275 decreased by the scrollbar's width and the scrollbar is drawn at the
2276 right side of the center slice.
2277 b) If the scrollbar won't be drawn then the boot menu entry's width
2278 is the width of the center slice.
2279 c) We don't necessary need the menu pixmap box to display the scrollbar.
2280 @item scrollbar_left_pad
2281 @tab The left scrollbar padding in pixels.
2282 Unused if ``scrollbar_slice`` is ``west``.
2283 @item scrollbar_right_pad
2284 @tab The right scrollbar padding in pixels.
2285 Unused if ``scrollbar_slice`` is ``east``.
2286 @item scrollbar_top_pad
2287 @tab The top scrollbar padding in pixels.
2288 @item scrollbar_bottom_pad
2289 @tab The bottom scrollbar padding in pixels.
2291 @tab Set to ``false`` to hide the boot menu.
2295 Canvas is a container that allows manual placement of components within it.
2296 It does not alter the positions of its child components. It assigns all
2297 child components their preferred sizes.
2300 The *hbox* container lays out its children from left to right, giving each
2301 one its preferred width. The height of each child is set to the maximum of
2302 the preferred heights of all children.
2305 The *vbox* container lays out its children from top to bottom, giving each
2306 one its preferred height. The width of each child is set to the maximum of
2307 the preferred widths of all children.
2311 @subsection Common properties
2313 The following properties are supported by all components:
2316 The distance from the left border of container to left border of the object in either of three formats:
2317 @multitable @columnfractions 0.2 0.7
2318 @item x @tab Value in pixels
2319 @item p% @tab Percentage
2320 @item p%+x @tab mixture of both
2323 The distance from the left border of container to left border of the object in same format.
2325 The width of object in same format.
2327 The height of object in same format.
2329 The identifier for the component. This can be any arbitrary string.
2330 The ID can be used by scripts to refer to various components in the GUI
2331 component tree. Currently, there is one special ID value that GRUB
2334 @multitable @columnfractions 0.2 0.7
2335 @item ``__timeout__``
2336 @tab Component with this ID will be updated by GRUB and will indicate
2337 time elapsed to an automatical boot of the default entry.
2338 Affected components: ``label``, ``circular_progress``, ``progress_bar``.
2345 @chapter Booting GRUB from the network
2347 The following instructions don't work for *-emu, i386-qemu, i386-coreboot,
2348 i386-multiboot, mips_loongson, mips-arc and mips_qemu_mips
2350 To generate a netbootable directory, run:
2354 grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/<platform>
2362 grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/i386-pc
2366 Then follow instructions printed out by grub-mknetdir on configuring your DHCP
2369 After GRUB has started, files on the TFTP server will be accessible via the
2370 @samp{(tftp)} device.
2372 The server IP address can be controlled by changing the
2373 @samp{(tftp)} device name to @samp{(tftp,@var{server-ip})}. Note that
2374 this should be changed both in the prefix and in any references to the
2375 device name in the configuration file.
2377 GRUB provides several environment variables which may be used to inspect or
2378 change the behaviour of the PXE device. In the following description
2379 @var{<interface>} is placeholder for the name of network interface (platform
2383 @item net_@var{<interface>}_ip
2384 The network interface's IP address. Read-only.
2386 @item net_@var{<interface>}_mac
2387 The network interface's MAC address. Read-only.
2389 @item net_@var{<interface>}_hostname
2390 The client host name provided by DHCP. Read-only.
2392 @item net_@var{<interface>}_domain
2393 The client domain name provided by DHCP. Read-only.
2395 @item net_@var{<interface>}_rootpath
2396 The path to the client's root disk provided by DHCP. Read-only.
2398 @item net_@var{<interface>}_extensionspath
2399 The path to additional DHCP vendor extensions provided by DHCP. Read-only.
2401 @item net_@var{<interface>}_boot_file
2402 The boot file name provided by DHCP. Read-only.
2404 @item net_@var{<interface>}_dhcp_server_name
2405 The name of the DHCP server responsible for these boot parameters.
2408 @item net_default_interface
2409 Initially set to name of network interface that was used to load grub.
2410 Read-write, although setting it affects only interpretation of
2411 @samp{net_default_ip} and @samp{net_default_mac}
2413 @item net_default_ip
2414 The IP address of default interface. Read-only. This is alias for the
2415 @samp{net_$@{net_default_interface@}_ip}.
2417 @item net_default_mac
2418 The default interface's MAC address. Read-only. This is alias for the
2419 @samp{net_$@{net_default_interface@}_mac}.
2421 @item net_default_server
2422 The default server used by network drives (@pxref{Device syntax}). Read-write,
2423 although setting this is only useful before opening a network device.
2428 @node Serial terminal
2429 @chapter Using GRUB via a serial line
2431 This chapter describes how to use the serial terminal support in GRUB.
2433 If you have many computers or computers with no display/keyboard, it
2434 could be very useful to control the computers through serial
2435 communications. To connect one computer with another via a serial line,
2436 you need to prepare a null-modem (cross) serial cable, and you may need
2437 to have multiport serial boards, if your computer doesn't have extra
2438 serial ports. In addition, a terminal emulator is also required, such as
2439 minicom. Refer to a manual of your operating system, for more
2442 As for GRUB, the instruction to set up a serial terminal is quite
2443 simple. Here is an example:
2447 grub> @kbd{serial --unit=0 --speed=9600}
2448 grub> @kbd{terminal_input serial; terminal_output serial}
2452 The command @command{serial} initializes the serial unit 0 with the
2453 speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
2454 you want to use COM2, you must specify @samp{--unit=1} instead. This
2455 command accepts many other options, so please refer to @ref{serial},
2458 The commands @command{terminal_input} (@pxref{terminal_input}) and
2459 @command{terminal_output} (@pxref{terminal_output}) choose which type of
2460 terminal you want to use. In the case above, the terminal will be a
2461 serial terminal, but you can also pass @code{console} to the command,
2462 as @samp{terminal_input serial console}. In this case, a terminal in which
2463 you press any key will be selected as a GRUB terminal. In the example above,
2464 note that you need to put both commands on the same command line, as you
2465 will lose the ability to type commands on the console after the first
2468 However, note that GRUB assumes that your terminal emulator is
2469 compatible with VT100 by default. This is true for most terminal
2470 emulators nowadays, but you should pass the option @option{--dumb} to
2471 the command if your terminal emulator is not VT100-compatible or
2472 implements few VT100 escape sequences. If you specify this option then
2473 GRUB provides you with an alternative menu interface, because the normal
2474 menu requires several fancy features of your terminal.
2477 @node Vendor power-on keys
2478 @chapter Using GRUB with vendor power-on keys
2480 Some laptop vendors provide an additional power-on button which boots another
2481 OS. GRUB supports such buttons with the @samp{GRUB_TIMEOUT_BUTTON},
2482 @samp{GRUB_DEFAULT_BUTTON}, @samp{GRUB_HIDDEN_TIMEOUT_BUTTON} and
2483 @samp{GRUB_BUTTON_CMOS_ADDRESS} variables in default/grub (@pxref{Simple
2484 configuration}). @samp{GRUB_TIMEOUT_BUTTON}, @samp{GRUB_DEFAULT_BUTTON} and
2485 @samp{GRUB_HIDDEN_TIMEOUT_BUTTON} are used instead of the corresponding
2486 variables without the @samp{_BUTTON} suffix when powered on using the special
2487 button. @samp{GRUB_BUTTON_CMOS_ADDRESS} is vendor-specific and partially
2488 model-specific. Values known to the GRUB team are:
2491 @item Dell XPS M1330M
2493 @item Dell XPS M1530
2495 @item Dell Latitude E4300
2497 @item Asus EeePC 1005PE
2501 To take full advantage of this function, install GRUB into the MBR
2502 (@pxref{Installing GRUB using grub-install}).
2504 If you have a laptop which has a similar feature and not in the above list
2505 could you figure your address and contribute?
2506 To discover the address do the following:
2512 sudo cat /dev/nvram | xxd > normal_button.txt
2514 @item boot using vendor button
2518 sudo cat /dev/nvram | xxd > normal_vendor.txt
2522 Then compare these text files and find where a bit was toggled. E.g. in
2523 case of Dell XPS it was:
2525 byte 0x47: 20 --> 28
2527 It's a bit number 3 as seen from following table:
2528 @multitable @columnfractions .2 .2
2539 0x47 is decimal 71. Linux nvram implementation cuts first 14 bytes of
2540 CMOS. So the real byte address in CMOS is 71+14=85
2541 So complete address is 85:3
2544 @chapter GRUB image files
2546 @c FIXME: parts of this section are specific to PC BIOS right now.
2548 GRUB consists of several images: a variety of bootstrap images for starting
2549 GRUB in various ways, a kernel image, and a set of modules which are
2550 combined with the kernel image to form a core image. Here is a short
2555 On PC BIOS systems, this image is the first part of GRUB to start. It is
2556 written to a master boot record (MBR) or to the boot sector of a partition.
2557 Because a PC boot sector is 512 bytes, the size of this image is exactly 512
2560 The sole function of @file{boot.img} is to read the first sector of the core
2561 image from a local disk and jump to it. Because of the size restriction,
2562 @file{boot.img} cannot understand any file system structure, so
2563 @command{grub-install} hardcodes the location of the first sector of the
2564 core image into @file{boot.img} when installing GRUB.
2567 This image is used as the first sector of the core image when booting from a
2568 hard disk. It reads the rest of the core image into memory and starts the
2569 kernel. Since file system handling is not yet available, it encodes the
2570 location of the core image using a block list format.
2573 This image is used as the first sector of the core image when booting from a
2574 CD-ROM drive. It performs a similar function to @file{diskboot.img}.
2577 This image is used as the start of the core image when booting from the
2578 network using PXE. @xref{Network}.
2581 This image may be placed at the start of the core image in order to make
2582 GRUB look enough like a Linux kernel that it can be booted by LILO using an
2583 @samp{image=} section.
2586 This image contains GRUB's basic run-time facilities: frameworks for device
2587 and file handling, environment variables, the rescue mode command-line
2588 parser, and so on. It is rarely used directly, but is built into all core
2592 This is the core image of GRUB. It is built dynamically from the kernel
2593 image and an arbitrary list of modules by the @command{grub-mkimage}
2594 program. Usually, it contains enough modules to access @file{/boot/grub},
2595 and loads everything else (including menu handling, the ability to load
2596 target operating systems, and so on) from the file system at run-time. The
2597 modular design allows the core image to be kept small, since the areas of
2598 disk where it must be installed are often as small as 32KB.
2600 @xref{BIOS installation}, for details on where the core image can be
2601 installed on PC systems.
2604 Everything else in GRUB resides in dynamically loadable modules. These are
2605 often loaded automatically, or built into the core image if they are
2606 essential, but may also be loaded manually using the @command{insmod}
2607 command (@pxref{insmod}).
2610 @heading For GRUB Legacy users
2612 GRUB 2 has a different design from GRUB Legacy, and so correspondences with
2613 the images it used cannot be exact. Nevertheless, GRUB Legacy users often
2614 ask questions in the terms they are familiar with, and so here is a brief
2615 guide to how GRUB 2's images relate to that.
2619 Stage 1 from GRUB Legacy was very similar to @file{boot.img} in GRUB 2, and
2620 they serve the same function.
2623 In GRUB Legacy, Stage 1.5's function was to include enough filesystem code
2624 to allow the much larger Stage 2 to be read from an ordinary filesystem. In
2625 this respect, its function was similar to @file{core.img} in GRUB 2.
2626 However, @file{core.img} is much more capable than Stage 1.5 was; since it
2627 offers a rescue shell, it is sometimes possible to recover manually in the
2628 event that it is unable to load any other modules, for example if partition
2629 numbers have changed. @file{core.img} is built in a more flexible way,
2630 allowing GRUB 2 to support reading modules from advanced disk types such as
2633 GRUB Legacy could run with only Stage 1 and Stage 2 in some limited
2634 configurations, while GRUB 2 requires @file{core.img} and cannot work
2638 GRUB 2 has no single Stage 2 image. Instead, it loads modules from
2639 @file{/boot/grub} at run-time.
2641 @item stage2_eltorito
2642 In GRUB 2, images for booting from CD-ROM drives are now constructed using
2643 @file{cdboot.img} and @file{core.img}, making sure that the core image
2644 contains the @samp{iso9660} module. It is usually best to use the
2645 @command{grub-mkrescue} program for this.
2648 There is as yet no equivalent for @file{nbgrub} in GRUB 2; it was used by
2649 Etherboot and some other network boot loaders.
2652 In GRUB 2, images for PXE network booting are now constructed using
2653 @file{pxeboot.img} and @file{core.img}, making sure that the core image
2654 contains the @samp{pxe} and @samp{pxecmd} modules. @xref{Network}.
2657 @node Core image size limitation
2658 @chapter Core image size limitation
2660 Heavily limited platforms:
2662 @item i386-pc (normal and PXE): the core image size (compressed) is limited by 458240 bytes.
2663 kernel.img (.text + .data + .bss, uncompressed) is limited by 392704 bytes.
2664 module size (uncompressed) + kernel.img (.text + .data, uncompressed) is limited by the size of contiguous chunk at 1M address.
2665 @item sparc64-ieee1275: kernel.img (.text + .data + .bss) + modules + 256K (stack) + 2M (heap) is limited by space available at 0x4400. On most platforms it's just 3 or 4M since ieee1275 maps only so much.
2666 @item i386-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by memory available at 0x10000, at most 596K
2669 Lightly limited platforms:
2672 @item *-xen: limited only by adress space and RAM size.
2673 @item i386-qemu: kernel.img (.text + .data + .bss) is limited by 392704 bytes.
2674 (core.img would be limited by ROM size but it's unlimited on qemu
2675 @item All EFI platforms: limited by contiguous RAM size and possibly firmware bugs
2676 @item Coreboot and multiboot. kernel.img (.text + .data + .bss) is limited by 392704 bytes.
2677 module size is limited by the size of contiguous chunk at 1M address.
2678 @item mipsel-loongson (ELF), mips(el)-qemu_mips (ELF): if uncompressed:
2679 kernel.img (.text + .data) + modules is limited by the space from 80200000 forward
2681 kernel.img (.text + .data, uncompressed) + modules (uncompressed)
2682 + (modules + kernel.img (.text + .data)) (compressed)
2683 + decompressor is limited by the space from 80200000 forward
2684 @item mipsel-loongson (Flash), mips(el)-qemu_mips (Flash): kernel.img (.text + .data) + modules is limited by the space from 80200000 forward
2685 core.img (final) is limited by flash size (512K on yeeloong and fulooong)
2686 @item mips-arc: if uncompressed:
2687 kernel.img (.text + .data) is limited by the space from 8bd00000 forward
2688 modules + dummy decompressor is limited by the space from 8bd00000 backward
2690 kernel.img (.text + .data, uncompressed) is limited by the space from 8bd00000 forward
2691 modules (uncompressed) + (modules + kernel.img (.text + .data)) (compressed, aligned to 1M)
2692 + 1M (decompressor + scratch space) is limited by the space from 8bd00000 backward
2693 @item powerpc-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by space available at 0x200000
2697 @chapter Filesystem syntax and semantics
2699 GRUB uses a special syntax for specifying disk drives which can be
2700 accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
2701 between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
2702 device is equivalent to which OS device. Normally, that will be clear if
2703 you see the files in a device or use the command @command{search}
2707 * Device syntax:: How to specify devices
2708 * File name syntax:: How to specify files
2709 * Block list syntax:: How to specify block lists
2714 @section How to specify devices
2716 The device syntax is like this:
2719 @code{(@var{device}[,@var{partmap-name1}@var{part-num1}[,@var{partmap-name2}@var{part-num2}[,...]]])}
2722 @samp{[]} means the parameter is optional. @var{device} depends on the disk
2723 driver in use. BIOS and EFI disks use either @samp{fd} or @samp{hd} followed
2724 by a digit, like @samp{fd0}, or @samp{cd}.
2725 AHCI, PATA (ata), crypto, USB use the name of driver followed by a number.
2726 Memdisk and host are limited to one disk and so it's refered just by driver
2728 RAID (md), ofdisk (ieee1275 and nand), LVM (lvm), LDM, virtio (vdsk)
2729 and arcdisk (arc) use intrinsic name of disk prefixed by driver name.
2730 Additionally just ``nand'' refers to the disk aliased as ``nand''.
2731 Conflicts are solved by suffixing a number if necessarry.
2732 Commas need to be escaped.
2733 Loopback uses whatever name specified to @command{loopback} command.
2734 Hostdisk uses names specified in device.map as long as it's of the form
2735 [fhc]d[0-9]* or hostdisk/<OS DEVICE>.
2736 For crypto and RAID (md) additionally you can use the syntax
2737 <driver name>uuid/<uuid>. For LVM additionally you can use the syntax
2738 lvmid/<volume-group-uuid>/<volume-uuid>.
2748 (cryptouuid/123456789abcdef0123456789abcdef0)
2749 (mduuid/123456789abcdef0123456789abcdef0)
2751 (lvmid/F1ikgD-2RES-306G-il9M-7iwa-4NKW-EbV1NV/eLGuCQ-L4Ka-XUgR-sjtJ-ffch-bajr-fCNfz5)
2755 (ieee1275//pci@@1f\,0/ide@@d/disk@@2)
2763 @var{part-num} represents the partition number of @var{device}, starting
2764 from one. @var{partname} is optional but is recommended since disk may have
2765 several top-level partmaps. Specifying third and later component you can access
2768 The syntax @samp{(hd0)} represents using the entire disk (or the
2769 MBR when installing GRUB), while the syntax @samp{(hd0,1)}
2770 represents using the first partition of the disk (or the boot sector
2771 of the partition when installing GRUB).
2782 If you enabled the network support, the special drives
2783 @code{(@var{protocol}[,@var{server}])} are also available. Supported protocols
2784 are @samp{http} and @samp{tftp}. If @var{server} is omitted, value of
2785 environment variable @samp{net_default_server} is used.
2786 Before using the network drive, you must initialize the network.
2787 @xref{Network}, for more information.
2789 If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
2790 a GRUB bootable CD-ROM}, for details.
2793 @node File name syntax
2794 @section How to specify files
2796 There are two ways to specify files, by @dfn{absolute file name} and by
2799 An absolute file name resembles a Unix absolute file name, using
2800 @samp{/} for the directory separator (not @samp{\} as in DOS). One
2801 example is @samp{(hd0,1)/boot/grub/grub.cfg}. This means the file
2802 @file{/boot/grub/grub.cfg} in the first partition of the first hard
2803 disk. If you omit the device name in an absolute file name, GRUB uses
2804 GRUB's @dfn{root device} implicitly. So if you set the root device to,
2805 say, @samp{(hd1,1)} by the command @samp{set root=(hd1,1)} (@pxref{set}),
2806 then @code{/boot/kernel} is the same as @code{(hd1,1)/boot/kernel}.
2808 On ZFS filesystem the first path component must be
2809 @var{volume}@samp{@@}[@var{snapshot}].
2810 So @samp{/rootvol@@snap-129/boot/grub/grub.cfg} refers to file
2811 @samp{/boot/grub/grub.cfg} in snapshot of volume @samp{rootvol} with name
2812 @samp{snap-129}. Trailing @samp{@@} after volume name is mandatory even if
2813 snapshot name is omitted.
2816 @node Block list syntax
2817 @section How to specify block lists
2819 A block list is used for specifying a file that doesn't appear in the
2820 filesystem, like a chainloader. The syntax is
2821 @code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
2825 @code{0+100,200+1,300+300}
2828 This represents that GRUB should read blocks 0 through 99, block 200,
2829 and blocks 300 through 599. If you omit an offset, then GRUB assumes
2832 Like the file name syntax (@pxref{File name syntax}), if a blocklist
2833 does not contain a device name, then GRUB uses GRUB's @dfn{root
2834 device}. So @code{(hd0,2)+1} is the same as @code{+1} when the root
2835 device is @samp{(hd0,2)}.
2839 @chapter GRUB's user interface
2841 GRUB has both a simple menu interface for choosing preset entries from a
2842 configuration file, and a highly flexible command-line for performing
2843 any desired combination of boot commands.
2845 GRUB looks for its configuration file as soon as it is loaded. If one
2846 is found, then the full menu interface is activated using whatever
2847 entries were found in the file. If you choose the @dfn{command-line} menu
2848 option, or if the configuration file was not found, then GRUB drops to
2849 the command-line interface.
2852 * Command-line interface:: The flexible command-line interface
2853 * Menu interface:: The simple menu interface
2854 * Menu entry editor:: Editing a menu entry
2858 @node Command-line interface
2859 @section The flexible command-line interface
2861 The command-line interface provides a prompt and after it an editable
2862 text area much like a command-line in Unix or DOS. Each command is
2863 immediately executed after it is entered@footnote{However, this
2864 behavior will be changed in the future version, in a user-invisible
2865 way.}. The commands (@pxref{Command-line and menu entry commands}) are a
2866 subset of those available in the configuration file, used with exactly
2869 Cursor movement and editing of the text on the line can be done via a
2870 subset of the functions available in the Bash shell:
2875 Move forward one character.
2879 Move back one character.
2883 Move to the start of the line.
2887 Move the the end of the line.
2891 Delete the character underneath the cursor.
2895 Delete the character to the left of the cursor.
2898 Kill the text from the current cursor position to the end of the line.
2901 Kill backward from the cursor to the beginning of the line.
2904 Yank the killed text back into the buffer at the cursor.
2908 Move up through the history list.
2912 Move down through the history list.
2915 When typing commands interactively, if the cursor is within or before
2916 the first word in the command-line, pressing the @key{TAB} key (or
2917 @key{C-i}) will display a listing of the available commands, and if the
2918 cursor is after the first word, the @kbd{@key{TAB}} will provide a
2919 completion listing of disks, partitions, and file names depending on the
2920 context. Note that to obtain a list of drives, one must open a
2921 parenthesis, as @command{root (}.
2923 Note that you cannot use the completion functionality in the TFTP
2924 filesystem. This is because TFTP doesn't support file name listing for
2928 @node Menu interface
2929 @section The simple menu interface
2931 The menu interface is quite easy to use. Its commands are both
2932 reasonably intuitive and described on screen.
2934 Basically, the menu interface provides a list of @dfn{boot entries} to
2935 the user to choose from. Use the arrow keys to select the entry of
2936 choice, then press @key{RET} to run it. An optional timeout is
2937 available to boot the default entry (the first one if not set), which is
2938 aborted by pressing any key.
2940 Commands are available to enter a bare command-line by pressing @key{c}
2941 (which operates exactly like the non-config-file version of GRUB, but
2942 allows one to return to the menu if desired by pressing @key{ESC}) or to
2943 edit any of the @dfn{boot entries} by pressing @key{e}.
2945 If you protect the menu interface with a password (@pxref{Security}),
2946 all you can do is choose an entry by pressing @key{RET}, or press
2947 @key{p} to enter the password.
2950 @node Menu entry editor
2951 @section Editing a menu entry
2953 The menu entry editor looks much like the main menu interface, but the
2954 lines in the menu are individual commands in the selected entry instead
2957 If an @key{ESC} is pressed in the editor, it aborts all the changes made
2958 to the configuration entry and returns to the main menu interface.
2960 Each line in the menu entry can be edited freely, and you can add new lines
2961 by pressing @key{RET} at the end of a line. To boot the edited entry, press
2964 Although GRUB unfortunately does not support @dfn{undo}, you can do almost
2965 the same thing by just returning to the main menu using @key{ESC}.
2969 @chapter GRUB environment variables
2971 GRUB supports environment variables which are rather like those offered by
2972 all Unix-like systems. Environment variables have a name, which is unique
2973 and is usually a short identifier, and a value, which is an arbitrary string
2974 of characters. They may be set (@pxref{set}), unset (@pxref{unset}), or
2975 looked up (@pxref{Shell-like scripting}) by name.
2977 A number of environment variables have special meanings to various parts of
2978 GRUB. Others may be used freely in GRUB configuration files.
2982 * Special environment variables::
2983 * Environment block::
2987 @node Special environment variables
2988 @section Special environment variables
2990 These variables have special meaning to GRUB.
2994 * check_signatures::
3010 * menu_color_highlight::
3011 * menu_color_normal::
3012 * net_@var{<interface>}_boot_file::
3013 * net_@var{<interface>}_dhcp_server_name::
3014 * net_@var{<interface>}_domain::
3015 * net_@var{<interface>}_extensionspath::
3016 * net_@var{<interface>}_hostname::
3017 * net_@var{<interface>}_ip::
3018 * net_@var{<interface>}_mac::
3019 * net_@var{<interface>}_rootpath::
3020 * net_default_interface::
3023 * net_default_server::
3027 * pxe_default_gateway::
3028 * pxe_default_server::
3039 When chain-loading another boot loader (@pxref{Chain-loading}), GRUB may
3040 need to know what BIOS drive number corresponds to the root device
3041 (@pxref{root}) so that it can set up registers properly. If the
3042 @var{biosnum} variable is set, it overrides GRUB's own means of guessing
3045 For an alternative approach which also changes BIOS drive mappings for the
3046 chain-loaded system, @pxref{drivemap}.
3049 @node check_signatures
3050 @subsection check_signatures
3052 This variable controls whether GRUB enforces digital signature
3053 validation on loaded files. @xref{Using digital signatures}.
3058 When executing a menu entry, GRUB sets the @var{chosen} variable to the
3059 title of the entry being executed.
3061 If the menu entry is in one or more submenus, then @var{chosen} is set to
3062 the titles of each of the submenus starting from the top level followed by
3063 the title of the menu entry itself, separated by @samp{>}.
3069 The location from which @file{core.img} was loaded as an absolute
3070 directory name (@pxref{File name syntax}). This is set by GRUB at
3071 startup based on information returned by platform firmware. Not every
3072 platform provides this information and some may return only device
3076 @node color_highlight
3077 @subsection color_highlight
3079 This variable contains the ``highlight'' foreground and background terminal
3080 colors, separated by a slash (@samp{/}). Setting this variable changes
3081 those colors. For the available color names, @pxref{color_normal}.
3083 The default is @samp{black/white}.
3087 @subsection color_normal
3089 This variable contains the ``normal'' foreground and background terminal
3090 colors, separated by a slash (@samp{/}). Setting this variable changes
3091 those colors. Each color must be a name from the following list:
3112 The default is @samp{white/black}.
3114 The color support support varies from terminal to terminal.
3116 @samp{morse} has no color support at all.
3118 @samp{mda_text} color support is limited to highlighting by
3119 black/white reversal.
3121 @samp{console} on ARC, EMU and IEEE1275, @samp{serial_*} and
3122 @samp{spkmodem} are governed by terminfo and support
3123 only 8 colors if in modes @samp{vt100-color} (default for console on emu),
3124 @samp{arc} (default for console on ARC), @samp{ieee1275} (default
3125 for console on IEEE1275). When in mode @samp{vt100}
3126 then the color support is limited to highlighting by black/white
3127 reversal. When in mode @samp{dumb} there is no color support.
3129 When console supports no colors this setting is ignored.
3130 When console supports 8 colors, then the colors from the
3131 second half of the previous list are mapped to the
3132 matching colors of first half.
3134 @samp{console} on EFI and BIOS and @samp{vga_text} support all 16 colors.
3136 @samp{gfxterm} supports all 16 colors and would be theoretically extendable
3137 to support whole rgb24 palette but currently there is no compelling reason
3138 to go beyond the current 16 colors.
3143 This variable may be set to enable debugging output from various components
3144 of GRUB. The value is a list of debug facility names separated by
3145 whitespace or @samp{,}, or @samp{all} to enable all available debugging
3146 output. The facility names are the first argument to grub_dprintf. Consult
3147 source for more details.
3153 If this variable is set, it identifies a menu entry that should be selected
3154 by default, possibly after a timeout (@pxref{timeout}). The entry may be
3155 identified by number or by id.
3157 For example, if you have:
3160 menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux {
3165 then you can make this the default using:
3168 default=example-gnu-linux
3171 If the entry is in a submenu, then it must be identified using the titles of
3172 each of the submenus starting from the top level followed by the number or
3173 title of the menu entry itself, separated by @samp{>}. For example, take
3174 the following menu structure:
3187 ``Menu Entry 3'' would then be identified as
3188 @samp{Submenu 2>Submenu 3>Menu Entry 3}.
3190 This variable is often set by @samp{GRUB_DEFAULT} (@pxref{Simple
3191 configuration}), @command{grub-set-default}, or @command{grub-reboot}.
3195 @subsection fallback
3197 If this variable is set, it identifies a menu entry that should be selected
3198 if the default menu entry fails to boot. Entries are identified in the same
3199 way as for @samp{default} (@pxref{default}).
3205 If this variable is set, it sets the resolution used on the @samp{gfxterm}
3206 graphical terminal. Note that you can only use modes which your graphics
3207 card supports via VESA BIOS Extensions (VBE), so for example native LCD
3208 panel resolutions may not be available. The default is @samp{auto}, which
3209 selects a platform-specific default that should look reasonable. Supported
3210 modes can be listed by @samp{videoinfo} command in GRUB.
3212 The resolution may be specified as a sequence of one or more modes,
3213 separated by commas (@samp{,}) or semicolons (@samp{;}); each will be tried
3214 in turn until one is found. Each mode should be either @samp{auto},
3215 @samp{@var{width}x@var{height}}, or
3216 @samp{@var{width}x@var{height}x@var{depth}}.
3220 @subsection gfxpayload
3222 If this variable is set, it controls the video mode in which the Linux
3223 kernel starts up, replacing the @samp{vga=} boot option (@pxref{linux}). It
3224 may be set to @samp{text} to force the Linux kernel to boot in normal text
3225 mode, @samp{keep} to preserve the graphics mode set using @samp{gfxmode}, or
3226 any of the permitted values for @samp{gfxmode} to set a particular graphics
3227 mode (@pxref{gfxmode}).
3229 Depending on your kernel, your distribution, your graphics card, and the
3230 phase of the moon, note that using this option may cause GNU/Linux to suffer
3231 from various display problems, particularly during the early part of the
3232 boot sequence. If you have problems, set this variable to @samp{text} and
3233 GRUB will tell Linux to boot in normal text mode.
3235 The default is platform-specific. On platforms with a native text mode
3236 (such as PC BIOS platforms), the default is @samp{text}. Otherwise the
3237 default may be @samp{auto} or a specific video mode.
3239 This variable is often set by @samp{GRUB_GFXPAYLOAD_LINUX} (@pxref{Simple
3244 @subsection gfxterm_font
3246 If this variable is set, it names a font to use for text on the
3247 @samp{gfxterm} graphical terminal. Otherwise, @samp{gfxterm} may use any
3252 @subsection grub_cpu
3254 In normal mode (@pxref{normal}), GRUB sets the @samp{grub_cpu} variable to
3255 the CPU type for which GRUB was built (e.g. @samp{i386} or @samp{powerpc}).
3259 @subsection grub_platform
3261 In normal mode (@pxref{normal}), GRUB sets the @samp{grub_platform} variable
3262 to the platform for which GRUB was built (e.g. @samp{pc} or @samp{efi}).
3268 If this variable is set, it names a directory in which the GRUB graphical
3269 menu should look for icons after looking in the theme's @samp{icons}
3270 directory. @xref{Theme file format}.
3276 If this variable is set, it names the language code that the
3277 @command{gettext} command (@pxref{gettext}) uses to translate strings. For
3278 example, French would be named as @samp{fr}, and Simplified Chinese as
3281 @command{grub-mkconfig} (@pxref{Simple configuration}) will try to set a
3282 reasonable default for this variable based on the system locale.
3286 @subsection locale_dir
3288 If this variable is set, it names the directory where translation files may
3289 be found (@pxref{gettext}), usually @file{/boot/grub/locale}. Otherwise,
3290 internationalization is disabled.
3292 @command{grub-mkconfig} (@pxref{Simple configuration}) will set a reasonable
3293 default for this variable if internationalization is needed and any
3294 translation files are available.
3297 @node menu_color_highlight
3298 @subsection menu_color_highlight
3300 This variable contains the foreground and background colors to be used for
3301 the highlighted menu entry, separated by a slash (@samp{/}). Setting this
3302 variable changes those colors. For the available color names,
3303 @pxref{color_normal}.
3305 The default is the value of @samp{color_highlight}
3306 (@pxref{color_highlight}).
3309 @node menu_color_normal
3310 @subsection menu_color_normal
3312 This variable contains the foreground and background colors to be used for
3313 non-highlighted menu entries, separated by a slash (@samp{/}). Setting this
3314 variable changes those colors. For the available color names,
3315 @pxref{color_normal}.
3317 The default is the value of @samp{color_normal} (@pxref{color_normal}).
3320 @node net_@var{<interface>}_boot_file
3321 @subsection net_@var{<interface>}_boot_file
3326 @node net_@var{<interface>}_dhcp_server_name
3327 @subsection net_@var{<interface>}_dhcp_server_name
3332 @node net_@var{<interface>}_domain
3333 @subsection net_@var{<interface>}_domain
3338 @node net_@var{<interface>}_extensionspath
3339 @subsection net_@var{<interface>}_extensionspath
3344 @node net_@var{<interface>}_hostname
3345 @subsection net_@var{<interface>}_hostname
3350 @node net_@var{<interface>}_ip
3351 @subsection net_@var{<interface>}_ip
3356 @node net_@var{<interface>}_mac
3357 @subsection net_@var{<interface>}_mac
3362 @node net_@var{<interface>}_rootpath
3363 @subsection net_@var{<interface>}_rootpath
3368 @node net_default_interface
3369 @subsection net_default_interface
3374 @node net_default_ip
3375 @subsection net_default_ip
3380 @node net_default_mac
3381 @subsection net_default_mac
3386 @node net_default_server
3387 @subsection net_default_server
3395 If set to @samp{1}, pause output after each screenful and wait for keyboard
3396 input. The default is not to pause output.
3402 The location of the @samp{/boot/grub} directory as an absolute file name
3403 (@pxref{File name syntax}). This is normally set by GRUB at startup based
3404 on information provided by @command{grub-install}. GRUB modules are
3405 dynamically loaded from this directory, so it must be set correctly in order
3406 for many parts of GRUB to work.
3410 @subsection pxe_blksize
3415 @node pxe_default_gateway
3416 @subsection pxe_default_gateway
3421 @node pxe_default_server
3422 @subsection pxe_default_server
3430 The root device name (@pxref{Device syntax}). Any file names that do not
3431 specify an explicit device name are read from this device. The default is
3432 normally set by GRUB at startup based on the value of @samp{prefix}
3435 For example, if GRUB was installed to the first partition of the first hard
3436 disk, then @samp{prefix} might be set to @samp{(hd0,msdos1)/boot/grub} and
3437 @samp{root} to @samp{hd0,msdos1}.
3441 @subsection superusers
3443 This variable may be set to a list of superuser names to enable
3444 authentication support. @xref{Security}.
3450 This variable may be set to a directory containing a GRUB graphical menu
3451 theme. @xref{Theme file format}.
3453 This variable is often set by @samp{GRUB_THEME} (@pxref{Simple
3460 If this variable is set, it specifies the time in seconds to wait for
3461 keyboard input before booting the default menu entry. A timeout of @samp{0}
3462 means to boot the default entry immediately without displaying the menu; a
3463 timeout of @samp{-1} (or unset) means to wait indefinitely.
3465 This variable is often set by @samp{GRUB_TIMEOUT} or
3466 @samp{GRUB_HIDDEN_TIMEOUT} (@pxref{Simple configuration}).
3469 @node Environment block
3470 @section The GRUB environment block
3472 It is often useful to be able to remember a small amount of information from
3473 one boot to the next. For example, you might want to set the default menu
3474 entry based on what was selected the last time. GRUB deliberately does not
3475 implement support for writing files in order to minimise the possibility of
3476 the boot loader being responsible for file system corruption, so a GRUB
3477 configuration file cannot just create a file in the ordinary way. However,
3478 GRUB provides an ``environment block'' which can be used to save a small
3481 The environment block is a preallocated 1024-byte file, which normally lives
3482 in @file{/boot/grub/grubenv} (although you should not assume this). At boot
3483 time, the @command{load_env} command (@pxref{load_env}) loads environment
3484 variables from it, and the @command{save_env} (@pxref{save_env}) command
3485 saves environment variables to it. From a running system, the
3486 @command{grub-editenv} utility can be used to edit the environment block.
3488 For safety reasons, this storage is only available when installed on a plain
3489 disk (no LVM or RAID), using a non-checksumming filesystem (no ZFS), and
3490 using BIOS or EFI functions (no ATA, USB or IEEE1275).
3492 @command{grub-mkconfig} uses this facility to implement
3493 @samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}).
3497 @chapter The list of available commands
3499 In this chapter, we list all commands that are available in GRUB.
3501 Commands belong to different groups. A few can only be used in
3502 the global section of the configuration file (or ``menu''); most
3503 of them can be entered on the command-line and can be used either
3504 anywhere in the menu or specifically in the menu entries.
3506 In rescue mode, only the @command{insmod} (@pxref{insmod}), @command{ls}
3507 (@pxref{ls}), @command{set} (@pxref{set}), and @command{unset}
3508 (@pxref{unset}) commands are normally available. If you end up in rescue
3509 mode and do not know what to do, then @pxref{GRUB only offers a rescue
3513 * Menu-specific commands::
3514 * General commands::
3515 * Command-line and menu entry commands::
3516 * Networking commands::
3520 @node Menu-specific commands
3521 @section The list of commands for the menu only
3523 The semantics used in parsing the configuration file are the following:
3527 The files @emph{must} be in plain-text format.
3530 @samp{#} at the beginning of a line in a configuration file means it is
3534 Options are separated by spaces.
3537 All numbers can be either decimal or hexadecimal. A hexadecimal number
3538 must be preceded by @samp{0x}, and is case-insensitive.
3541 These commands can only be used in the menu:
3544 * menuentry:: Start a menu entry
3545 * submenu:: Group menu entries
3550 @subsection menuentry
3552 @deffn Command menuentry @var{title} @
3553 [@option{--class=class} @dots{}] [@option{--users=users}] @
3554 [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @
3555 [@var{arg} @dots{}] @{ @var{command}; @dots{} @}
3556 This defines a GRUB menu entry named @var{title}. When this entry is
3557 selected from the menu, GRUB will set the @var{chosen} environment variable
3558 to value of @option{--id} if @option{--id} is given, execute the list of
3559 commands given within braces, and if the last command in the list returned
3560 successfully and a kernel was loaded it will execute the @command{boot} command.
3562 The @option{--class} option may be used any number of times to group menu
3563 entries into classes. Menu themes may display different classes using
3566 The @option{--users} option grants specific users access to specific menu
3567 entries. @xref{Security}.
3569 The @option{--unrestricted} option grants all users access to specific menu
3570 entries. @xref{Security}.
3572 The @option{--hotkey} option associates a hotkey with a menu entry.
3573 @var{key} may be a single letter, or one of the aliases @samp{backspace},
3574 @samp{tab}, or @samp{delete}.
3576 The @option{--id} may be used to associate unique identifier with a menu entry.
3577 @var{id} is string of ASCII aphanumeric characters, underscore and hyphen
3578 and should not start with a digit.
3580 All other arguments including @var{title} are passed as positional parameters
3581 when list of commands is executed with @var{title} always assigned to @code{$1}.
3588 @deffn Command submenu @var{title} @
3589 [@option{--class=class} @dots{}] [@option{--users=users}] @
3590 [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @
3591 @{ @var{menu entries} @dots{} @}
3592 This defines a submenu. An entry called @var{title} will be added to the
3593 menu; when that entry is selected, a new menu will be displayed showing all
3594 the entries within this submenu.
3596 All options are the same as in the @command{menuentry} command
3597 (@pxref{menuentry}).
3601 @node General commands
3602 @section The list of general commands
3604 Commands usable anywhere in the menu and in the command-line.
3607 * serial:: Set up a serial device
3608 * terminal_input:: Manage input terminals
3609 * terminal_output:: Manage output terminals
3610 * terminfo:: Define terminal type
3617 @deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}]
3618 Initialize a serial device. @var{unit} is a number in the range 0-3
3619 specifying which serial port to use; default is 0, which corresponds to
3620 the port often called COM1. @var{port} is the I/O port where the UART
3621 is to be found; if specified it takes precedence over @var{unit}.
3622 @var{speed} is the transmission speed; default is 9600. @var{word} and
3623 @var{stop} are the number of data bits and stop bits. Data bits must
3624 be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
3625 bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
3626 @samp{even} and defaults to @samp{no}.
3628 The serial port is not used as a communication channel unless the
3629 @command{terminal_input} or @command{terminal_output} command is used
3630 (@pxref{terminal_input}, @pxref{terminal_output}).
3632 See also @ref{Serial terminal}.
3636 @node terminal_input
3637 @subsection terminal_input
3639 @deffn Command terminal_input [@option{--append}|@option{--remove}] @
3640 [terminal1] [terminal2] @dots{}
3641 List or select an input terminal.
3643 With no arguments, list the active and available input terminals.
3645 With @option{--append}, add the named terminals to the list of active input
3646 terminals; any of these may be used to provide input to GRUB.
3648 With @option{--remove}, remove the named terminals from the active list.
3650 With no options but a list of terminal names, make only the listed terminal
3655 @node terminal_output
3656 @subsection terminal_output
3658 @deffn Command terminal_output [@option{--append}|@option{--remove}] @
3659 [terminal1] [terminal2] @dots{}
3660 List or select an output terminal.
3662 With no arguments, list the active and available output terminals.
3664 With @option{--append}, add the named terminals to the list of active output
3665 terminals; all of these will receive output from GRUB.
3667 With @option{--remove}, remove the named terminals from the active list.
3669 With no options but a list of terminal names, make only the listed terminal
3675 @subsection terminfo
3677 @deffn Command terminfo [-a|-u|-v] [term]
3678 Define the capabilities of your terminal by giving the name of an entry in
3679 the terminfo database, which should correspond roughly to a @samp{TERM}
3680 environment variable in Unix.
3682 The currently available terminal types are @samp{vt100}, @samp{vt100-color},
3683 @samp{ieee1275}, and @samp{dumb}. If you need other terminal types, please
3684 contact us to discuss the best way to include support for these in GRUB.
3686 The @option{-a} (@option{--ascii}), @option{-u} (@option{--utf8}), and
3687 @option{-v} (@option{--visual-utf8}) options control how non-ASCII text is
3688 displayed. @option{-a} specifies an ASCII-only terminal; @option{-u}
3689 specifies logically-ordered UTF-8; and @option{-v} specifies
3690 "visually-ordered UTF-8" (in other words, arranged such that a terminal
3691 emulator without bidirectional text support will display right-to-left text
3692 in the proper order; this is not really proper UTF-8, but a workaround).
3694 If no option or terminal type is specified, the current terminal type is
3699 @node Command-line and menu entry commands
3700 @section The list of command-line and menu entry commands
3702 These commands are usable in the command-line and in menu entries. If
3703 you forget a command, you can run the command @command{help}
3707 * [:: Check file types and compare values
3708 * acpi:: Load ACPI tables
3709 * authenticate:: Check whether user is in user list
3710 * background_color:: Set background color for active terminal
3711 * background_image:: Load background image for active terminal
3712 * badram:: Filter out bad regions of RAM
3713 * blocklist:: Print a block list
3714 * boot:: Start up your operating system
3715 * cat:: Show the contents of a file
3716 * chainloader:: Chain-load another boot loader
3717 * clear:: Clear the screen
3718 * cmosclean:: Clear bit in CMOS
3719 * cmosdump:: Dump CMOS contents
3720 * cmostest:: Test bit in CMOS
3721 * cmp:: Compare two files
3722 * configfile:: Load a configuration file
3723 * cpuid:: Check for CPU features
3724 * crc:: Compute or check CRC32 checksums
3725 * cryptomount:: Mount a crypto device
3726 * date:: Display or set current date and time
3727 * devicetree:: Load a device tree blob
3728 * distrust:: Remove a pubkey from trusted keys
3729 * drivemap:: Map a drive to another
3730 * echo:: Display a line of text
3731 * eval:: Evaluate agruments as GRUB commands
3732 * export:: Export an environment variable
3733 * false:: Do nothing, unsuccessfully
3734 * gettext:: Translate a string
3735 * gptsync:: Fill an MBR based on GPT entries
3736 * halt:: Shut down your computer
3737 * hashsum:: Compute or check hash checksum
3738 * help:: Show help messages
3739 * initrd:: Load a Linux initrd
3740 * initrd16:: Load a Linux initrd (16-bit mode)
3741 * insmod:: Insert a module
3742 * keystatus:: Check key modifier status
3743 * linux:: Load a Linux kernel
3744 * linux16:: Load a Linux kernel (16-bit mode)
3745 * list_env:: List variables in environment block
3746 * list_trusted:: List trusted public keys
3747 * load_env:: Load variables from environment block
3748 * loadfont:: Load font files
3749 * loopback:: Make a device from a filesystem image
3750 * ls:: List devices or files
3751 * lsfonts:: List loaded fonts
3752 * lsmod:: Show loaded modules
3753 * md5sum:: Compute or check MD5 hash
3754 * module:: Load module for multiboot kernel
3755 * multiboot:: Load multiboot compliant kernel
3756 * nativedisk:: Switch to native disk drivers
3757 * normal:: Enter normal mode
3758 * normal_exit:: Exit from normal mode
3759 * parttool:: Modify partition table entries
3760 * password:: Set a clear-text password
3761 * password_pbkdf2:: Set a hashed password
3762 * play:: Play a tune
3763 * probe:: Retrieve device info
3764 * pxe_unload:: Unload the PXE environment
3765 * read:: Read user input
3766 * reboot:: Reboot your computer
3767 * regexp:: Test if regular expression matches string
3768 * rmmod:: Remove a module
3769 * save_env:: Save variables to environment block
3770 * search:: Search devices by file, label, or UUID
3771 * sendkey:: Emulate keystrokes
3772 * set:: Set an environment variable
3773 * sha1sum:: Compute or check SHA1 hash
3774 * sha256sum:: Compute or check SHA256 hash
3775 * sha512sum:: Compute or check SHA512 hash
3776 * sleep:: Wait for a specified number of seconds
3777 * source:: Read a configuration file in same context
3778 * test:: Check file types and compare values
3779 * true:: Do nothing, successfully
3780 * trust:: Add public key to list of trusted keys
3781 * unset:: Unset an environment variable
3782 * uppermem:: Set the upper memory size
3783 @comment * vbeinfo:: List available video modes
3784 * verify_detached:: Verify detached digital signature
3785 * videoinfo:: List available video modes
3791 @deffn Command @code{[} expression @code{]}
3792 Alias for @code{test @var{expression}} (@pxref{test}).
3799 @deffn Command acpi [@option{-1}|@option{-2}] @
3800 [@option{--exclude=table1,@dots{}}|@option{--load-only=table1,@dots{}}] @
3801 [@option{--oemid=id}] [@option{--oemtable=table}] @
3802 [@option{--oemtablerev=rev}] [@option{--oemtablecreator=creator}] @
3803 [@option{--oemtablecreatorrev=rev}] [@option{--no-ebda}] @
3805 Modern BIOS systems normally implement the Advanced Configuration and Power
3806 Interface (ACPI), and define various tables that describe the interface
3807 between an ACPI-compliant operating system and the firmware. In some cases,
3808 the tables provided by default only work well with certain operating
3809 systems, and it may be necessary to replace some of them.
3811 Normally, this command will replace the Root System Description Pointer
3812 (RSDP) in the Extended BIOS Data Area to point to the new tables. If the
3813 @option{--no-ebda} option is used, the new tables will be known only to
3814 GRUB, but may be used by GRUB's EFI emulation.
3819 @subsection authenticate
3820 @deffn Command authenticate [userlist]
3821 Check whether user is in @var{userlist} or listed in the value of variable
3822 @samp{superusers}. See @pxref{superusers} for valid user list format.
3823 If @samp{superusers} is empty, this command returns true. @xref{Security}.
3827 @node background_color
3828 @subsection background_color
3830 @deffn Command background_color color
3831 Set background color for active terminal. For valid color specifications see
3832 @pxref{Theme file format, ,Colors}. Background color can be changed only when
3833 using @samp{gfxterm} for terminal output.
3835 This command sets color of empty areas without text. Text background color
3836 is controlled by environment variables @var{color_normal}, @var{color_highlight},
3837 @var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}.
3841 @node background_image
3842 @subsection background_image
3844 @deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
3845 Load background image for active terminal from @var{file}. Image is stretched
3846 to fill up entire screen unless option @option{--mode} @samp{normal} is given.
3847 Without arguments remove currently loaded background image. Background image
3848 can be changed only when using @samp{gfxterm} for terminal output.
3856 @deffn Command badram addr,mask[,addr,mask...]
3860 This command notifies the memory manager that specified regions of
3861 RAM ought to be filtered out (usually, because they're damaged). This
3862 remains in effect after a payload kernel has been loaded by GRUB, as
3863 long as the loaded kernel obtains its memory map from GRUB. Kernels that
3864 support this include Linux, GNU Mach, the kernel of FreeBSD and Multiboot
3867 Syntax is the same as provided by the @uref{http://www.memtest.org/,
3868 Memtest86+ utility}: a list of address/mask pairs. Given a page-aligned
3869 address and a base address / mask pair, if all the bits of the page-aligned
3870 address that are enabled by the mask match with the base address, it means
3871 this page is to be filtered. This syntax makes it easy to represent patterns
3872 that are often result of memory damage, due to physical distribution of memory
3876 @subsection blocklist
3878 @deffn Command blocklist file
3879 Print a block list (@pxref{Block list syntax}) for @var{file}.
3887 Boot the OS or chain-loader which has been loaded. Only necessary if
3888 running the fully interactive command-line (it is implicit at the end of
3896 @deffn Command cat [@option{--dos}] file
3897 Display the contents of the file @var{file}. This command may be useful
3898 to remind you of your OS's root partition:
3901 grub> @kbd{cat /etc/fstab}
3904 If the @option{--dos} option is used, then carriage return / new line pairs
3905 will be displayed as a simple new line. Otherwise, the carriage return will
3906 be displayed as a control character (@samp{<d>}) to make it easier to see
3907 when boot problems are caused by a file formatted using DOS-style line
3913 @subsection chainloader
3915 @deffn Command chainloader [@option{--force}] file
3916 Load @var{file} as a chain-loader. Like any other file loaded by the
3917 filesystem code, it can use the blocklist notation (@pxref{Block list
3918 syntax}) to grab the first sector of the current partition with @samp{+1}.
3919 If you specify the option @option{--force}, then load @var{file} forcibly,
3920 whether it has a correct signature or not. This is required when you want to
3921 load a defective boot loader, such as SCO UnixWare 7.1.
3928 @deffn Command clear
3934 @subsection cmosclean
3936 @deffn Command cmosclean byte:bit
3937 Clear value of bit in CMOS at location @var{byte}:@var{bit}. This command
3938 is available only on platforms that support CMOS.
3943 @subsection cmosdump
3945 @deffn Dump CMOS contents
3946 Dump full CMOS contents as hexadecimal values. This command is available only
3947 on platforms that support CMOS.
3952 @subsection cmostest
3954 @deffn Command cmostest byte:bit
3955 Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status
3956 is zero if bit is set, non zero otherwise. This command is available only
3957 on platforms that support CMOS.
3964 @deffn Command cmp file1 file2
3965 Compare the file @var{file1} with the file @var{file2}. If they differ
3966 in size, print the sizes like this:
3969 Differ in size: 0x1234 [foo], 0x4321 [bar]
3972 If the sizes are equal but the bytes at an offset differ, then print the
3976 Differ at the offset 777: 0xbe [foo], 0xef [bar]
3979 If they are completely identical, nothing will be printed.
3984 @subsection configfile
3986 @deffn Command configfile file
3987 Load @var{file} as a configuration file. If @var{file} defines any menu
3988 entries, then show a menu containing them immediately. Any environment
3989 variable changes made by the commands in @var{file} will not be preserved
3990 after @command{configfile} returns.
3997 @deffn Command cpuid [-l]
3998 Check for CPU features. This command is only available on x86 systems.
4000 With the @option{-l} option, return true if the CPU supports long mode
4003 If invoked without options, this command currently behaves as if it had been
4004 invoked with @option{-l}. This may change in the future.
4011 @deffn Command crc arg @dots{}
4012 Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
4013 (@pxref{hashsum}) for full description.
4018 @subsection cryptomount
4020 @deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
4021 Setup access to encrypted device. If necessary, passphrase
4022 is requested interactively. Option @var{device} configures specific grub device
4023 (@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
4024 with specified @var{uuid}; option @option{-a} configures all detected encrypted
4025 devices; option @option{-b} configures all geli containers that have boot flag set.
4027 GRUB suports devices encrypted using LUKS and geli. Note that necessary modules (@var{luks} and @var{geli}) have to be loaded manually before this command can
4035 @deffn Command date [[year-]month-day] [hour:minute[:second]]
4036 With no arguments, print the current date and time.
4038 Otherwise, take the current date and time, change any elements specified as
4039 arguments, and set the result as the new date and time. For example, `date
4040 01-01' will set the current month and day to January 1, but leave the year,
4041 hour, minute, and second unchanged.
4048 @deffn Command devicetree file
4049 Load a device tree blob (.dtb) from a filesystem, for later use by a Linux
4050 kernel. Does not perform merging with any device tree supplied by firmware,
4051 but rather replaces it completely.
4056 @subsection distrust
4058 @deffn Command distrust pubkey_id
4059 Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys.
4060 @var{pubkey_id} is the last four bytes (eight hexadecimal digits) of
4061 the GPG v4 key id, which is also the output of @command{list_trusted}
4062 (@pxref{list_trusted}). Outside of GRUB, the key id can be obtained
4063 using @code{gpg --fingerprint}).
4064 These keys are used to validate signatures when environment variable
4065 @code{check_signatures} is set to @code{enforce}
4066 (@pxref{check_signatures}), and by some invocations of
4067 @command{verify_detached} (@pxref{verify_detached}). @xref{Using
4068 digital signatures}, for more information.
4072 @subsection drivemap
4074 @deffn Command drivemap @option{-l}|@option{-r}|[@option{-s}] @
4076 Without options, map the drive @var{from_drive} to the drive @var{to_drive}.
4077 This is necessary when you chain-load some operating systems, such as DOS,
4078 if such an OS resides at a non-first drive. For convenience, any partition
4079 suffix on the drive is ignored, so you can safely use @verb{'${root}'} as a
4080 drive specification.
4082 With the @option{-s} option, perform the reverse mapping as well, swapping
4085 With the @option{-l} option, list the current mappings.
4087 With the @option{-r} option, reset all mappings to the default values.
4092 drivemap -s (hd0) (hd1)
4100 @deffn Command echo [@option{-n}] [@option{-e}] string @dots{}
4101 Display the requested text and, unless the @option{-n} option is used, a
4102 trailing new line. If there is more than one string, they are separated by
4103 spaces in the output. As usual in GRUB commands, variables may be
4104 substituted using @samp{$@{var@}}.
4106 The @option{-e} option enables interpretation of backslash escapes. The
4107 following sequences are recognised:
4117 suppress trailing new line
4135 When interpreting backslash escapes, backslash followed by any other
4136 character will print that character.
4143 @deffn Command eval string ...
4144 Concatenate arguments together using single space as separator and evaluate
4145 result as sequence of GRUB commands.
4152 @deffn Command export envvar
4153 Export the environment variable @var{envvar}. Exported variables are visible
4154 to subsidiary configuration files loaded using @command{configfile}.
4161 @deffn Command false
4162 Do nothing, unsuccessfully. This is mainly useful in control constructs
4163 such as @code{if} and @code{while} (@pxref{Shell-like scripting}).
4170 @deffn Command gettext string
4171 Translate @var{string} into the current language.
4173 The current language code is stored in the @samp{lang} variable in GRUB's
4174 environment (@pxref{lang}). Translation files in MO format are read from
4175 @samp{locale_dir} (@pxref{locale_dir}), usually @file{/boot/grub/locale}.
4182 @deffn Command gptsync device [partition[+/-[type]]] @dots{}
4183 Disks using the GUID Partition Table (GPT) also have a legacy Master Boot
4184 Record (MBR) partition table for compatibility with the BIOS and with older
4185 operating systems. The legacy MBR can only represent a limited subset of
4186 GPT partition entries.
4188 This command populates the legacy MBR with the specified @var{partition}
4189 entries on @var{device}. Up to three partitions may be used.
4191 @var{type} is an MBR partition type code; prefix with @samp{0x} if you want
4192 to enter this in hexadecimal. The separator between @var{partition} and
4193 @var{type} may be @samp{+} to make the partition active, or @samp{-} to make
4194 it inactive; only one partition may be active. If both the separator and
4195 type are omitted, then the partition will be inactive.
4202 @deffn Command halt @option{--no-apm}
4203 The command halts the computer. If the @option{--no-apm} option
4204 is specified, no APM BIOS call is performed. Otherwise, the computer
4205 is shut down using APM.
4212 @deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
4213 Compute or verify file hashes. Hash type is selected with option @option{--hash}.
4214 Supported hashes are: @samp{adler32}, @samp{crc64}, @samp{crc32},
4215 @samp{crc32rfc1510}, @samp{crc24rfc2440}, @samp{md4}, @samp{md5},
4216 @samp{ripemd160}, @samp{sha1}, @samp{sha224}, @samp{sha256}, @samp{sha512},
4217 @samp{sha384}, @samp{tiger192}, @samp{tiger}, @samp{tiger2}, @samp{whirlpool}.
4218 Option @option{--uncompress} uncompresses files before computing hash.
4220 When list of files is given, hash of each file is computed and printed,
4221 followed by file name, each file on a new line.
4223 When option @option{--check} is given, it points to a file that contains
4224 list of @var{hash name} pairs in the same format as used by UNIX
4225 @command{md5sum} command. Option @option{--prefix}
4226 may be used to give directory where files are located. Hash verification
4227 stops after the first mismatch was found unless option @option{--keep-going}
4228 was given. The exit code @code{$?} is set to 0 if hash verification
4229 is successful. If it fails, @code{$?} is set to a nonzero value.
4236 @deffn Command help [pattern @dots{}]
4237 Display helpful information about builtin commands. If you do not
4238 specify @var{pattern}, this command shows short descriptions of all
4241 If you specify any @var{patterns}, it displays longer information
4242 about each of the commands whose names begin with those @var{patterns}.
4249 @deffn Command initrd file
4250 Load an initial ramdisk for a Linux kernel image, and set the appropriate
4251 parameters in the Linux setup area in memory. This may only be used after
4252 the @command{linux} command (@pxref{linux}) has been run. See also
4258 @subsection initrd16
4260 @deffn Command initrd16 file
4261 Load an initial ramdisk for a Linux kernel image to be booted in 16-bit
4262 mode, and set the appropriate parameters in the Linux setup area in memory.
4263 This may only be used after the @command{linux16} command (@pxref{linux16})
4264 has been run. See also @ref{GNU/Linux}.
4266 This command is only available on x86 systems.
4273 @deffn Command insmod module
4274 Insert the dynamic GRUB module called @var{module}.
4279 @subsection keystatus
4281 @deffn Command keystatus [@option{--shift}] [@option{--ctrl}] [@option{--alt}]
4282 Return true if the Shift, Control, or Alt modifier keys are held down, as
4283 requested by options. This is useful in scripting, to allow some user
4284 control over behaviour without having to wait for a keypress.
4286 Checking key modifier status is only supported on some platforms. If invoked
4287 without any options, the @command{keystatus} command returns true if and
4288 only if checking key modifier status is supported.
4295 @deffn Command linux file @dots{}
4296 Load a Linux kernel image from @var{file}. The rest of the line is passed
4297 verbatim as the @dfn{kernel command-line}. Any initrd must be reloaded
4298 after using this command (@pxref{initrd}).
4300 On x86 systems, the kernel will be booted using the 32-bit boot protocol.
4301 Note that this means that the @samp{vga=} boot option will not work; if you
4302 want to set a special video mode, you will need to use GRUB commands such as
4303 @samp{set gfxpayload=1024x768} or @samp{set gfxpayload=keep} (to keep the
4304 same mode as used in GRUB) instead. GRUB can automatically detect some uses
4305 of @samp{vga=} and translate them to appropriate settings of
4306 @samp{gfxpayload}. The @command{linux16} command (@pxref{linux16}) avoids
4314 @deffn Command linux16 file @dots{}
4315 Load a Linux kernel image from @var{file} in 16-bit mode. The rest of the
4316 line is passed verbatim as the @dfn{kernel command-line}. Any initrd must
4317 be reloaded after using this command (@pxref{initrd16}).
4319 The kernel will be booted using the traditional 16-bit boot protocol. As
4320 well as bypassing problems with @samp{vga=} described in @ref{linux}, this
4321 permits booting some other programs that implement the Linux boot protocol
4322 for the sake of convenience.
4324 This command is only available on x86 systems.
4329 @subsection list_env
4331 @deffn Command list_env [@option{--file} file]
4332 List all variables in the environment block file. @xref{Environment block}.
4334 The @option{--file} option overrides the default location of the
4339 @subsection list_trusted
4341 @deffn Command list_trusted
4342 List all public keys trusted by GRUB for validating signatures.
4343 The output is in GPG's v4 key fingerprint format (i.e., the output of
4344 @code{gpg --fingerprint}). The least significant four bytes (last
4345 eight hexadecimal digits) can be used as an argument to
4346 @command{distrust} (@pxref{distrust}).
4347 @xref{Using digital signatures}, for more information about uses for
4352 @subsection load_env
4354 @deffn Command load_env [@option{--file} file] [@option{--skip-sig}] [whitelisted_variable_name] @dots{}
4355 Load all variables from the environment block file into the environment.
4356 @xref{Environment block}.
4358 The @option{--file} option overrides the default location of the environment
4361 The @option{--skip-sig} option skips signature checking even when the
4362 value of environment variable @code{check_signatures} is set to
4363 @code{enforce} (@pxref{check_signatures}).
4365 If one or more variable names are provided as arguments, they are
4366 interpreted as a whitelist of variables to load from the environment
4367 block file. Variables set in the file but not present in the
4368 whitelist are ignored.
4370 The @option{--skip-sig} option should be used with care, and should
4371 always be used in concert with a whitelist of acceptable variables
4372 whose values should be set. Failure to employ a carefully constructed
4373 whitelist could result in reading a malicious value into critical
4374 environment variables from the file, such as setting
4375 @code{check_signatures=no}, modifying @code{prefix} to boot from an
4376 unexpected location or not at all, etc.
4378 When used with care, @option{--skip-sig} and the whitelist enable an
4379 administrator to configure a system to boot only signed
4380 configurations, but to allow the user to select from among multiple
4381 configurations, and to enable ``one-shot'' boot attempts and
4382 ``savedefault'' behavior. @xref{Using digital signatures}, for more
4388 @subsection loadfont
4390 @deffn Command loadfont file @dots{}
4391 Load specified font files. Unless absolute pathname is given, @var{file}
4392 is assumed to be in directory @samp{$prefix/fonts} with
4393 suffix @samp{.pf2} appended. @xref{Theme file format,,Fonts}.
4398 @subsection loopback
4400 @deffn Command loopback [@option{-d}] device file
4401 Make the device named @var{device} correspond to the contents of the
4402 filesystem image in @var{file}. For example:
4405 loopback loop0 /path/to/image
4409 With the @option{-d} option, delete a device previously created using this
4417 @deffn Command ls [arg @dots{}]
4418 List devices or files.
4420 With no arguments, print all devices known to GRUB.
4422 If the argument is a device name enclosed in parentheses (@pxref{Device
4423 syntax}), then print the name of the filesystem of that device.
4425 If the argument is a directory given as an absolute file name (@pxref{File
4426 name syntax}), then list the contents of that directory.
4433 @deffn Command lsfonts
4441 @deffn Command lsmod
4442 Show list of loaded modules.
4448 @deffn Command md5sum arg @dots{}
4449 Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum}
4450 (@pxref{hashsum}) for full description.
4456 @deffn Command module [--nounzip] file [arguments]
4457 Load a module for multiboot kernel image. The rest of the
4458 line is passed verbatim as the module command line.
4462 @subsection multiboot
4464 @deffn Command multiboot [--quirk-bad-kludge] [--quirk-modules-after-kernel] file @dots{}
4465 Load a multiboot kernel image from @var{file}. The rest of the
4466 line is passed verbatim as the @dfn{kernel command-line}. Any module must
4467 be reloaded after using this command (@pxref{module}).
4469 Some kernels have known problems. You need to specify --quirk-* for those.
4470 --quirk-bad-kludge is a problem seen in several products that they include
4471 loading kludge information with invalid data in ELF file. GRUB prior to 0.97
4472 and some custom builds prefered ELF information while 0.97 and GRUB 2
4473 use kludge. Use this option to ignore kludge.
4474 Known affected systems: old Solaris, SkyOS.
4476 --quirk-modules-after-kernel is needed for kernels which load at relatively
4477 high address e.g. 16MiB mark and can't cope with modules stuffed between
4478 1MiB mark and beginning of the kernel.
4479 Known afftected systems: VMWare.
4483 @subsection nativedisk
4485 @deffn Command nativedisk
4486 Switch from firmware disk drivers to native ones.
4487 Really useful only on platforms where both
4488 firmware and native disk drives are available.
4489 Currently i386-pc, i386-efi, i386-ieee1275 and
4496 @deffn Command normal [file]
4497 Enter normal mode and display the GRUB menu.
4499 In normal mode, commands, filesystem modules, and cryptography modules are
4500 automatically loaded, and the full GRUB script parser is available. Other
4501 modules may be explicitly loaded using @command{insmod} (@pxref{insmod}).
4503 If a @var{file} is given, then commands will be read from that file.
4504 Otherwise, they will be read from @file{$prefix/grub.cfg} if it exists.
4506 @command{normal} may be called from within normal mode, creating a nested
4507 environment. It is more usual to use @command{configfile}
4508 (@pxref{configfile}) for this.
4513 @subsection normal_exit
4515 @deffn Command normal_exit
4516 Exit normal mode (@pxref{normal}). If this instance of normal mode was not
4517 nested within another one, then return to rescue mode.
4522 @subsection parttool
4524 @deffn Command parttool partition commands
4525 Make various modifications to partition table entries.
4527 Each @var{command} is either a boolean option, in which case it must be
4528 followed with @samp{+} or @samp{-} (with no intervening space) to enable or
4529 disable that option, or else it takes a value in the form
4530 @samp{@var{command}=@var{value}}.
4532 Currently, @command{parttool} is only useful on DOS partition tables (also
4533 known as Master Boot Record, or MBR). On these partition tables, the
4534 following commands are available:
4537 @item @samp{boot} (boolean)
4538 When enabled, this makes the selected partition be the active (bootable)
4539 partition on its disk, clearing the active flag on all other partitions.
4540 This command is limited to @emph{primary} partitions.
4542 @item @samp{type} (value)
4543 Change the type of an existing partition. The value must be a number in the
4544 range 0-0xFF (prefix with @samp{0x} to enter it in hexadecimal).
4546 @item @samp{hidden} (boolean)
4547 When enabled, this hides the selected partition by setting the @dfn{hidden}
4548 bit in its partition type code; when disabled, unhides the selected
4549 partition by clearing this bit. This is useful only when booting DOS or
4550 Wwindows and multiple primary FAT partitions exist in one disk. See also
4557 @subsection password
4559 @deffn Command password user clear-password
4560 Define a user named @var{user} with password @var{clear-password}.
4565 @node password_pbkdf2
4566 @subsection password_pbkdf2
4568 @deffn Command password_pbkdf2 user hashed-password
4569 Define a user named @var{user} with password hash @var{hashed-password}.
4570 Use @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
4571 to generate password hashes. @xref{Security}.
4578 @deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] @dots{}
4581 If the argument is a file name (@pxref{File name syntax}), play the tune
4582 recorded in it. The file format is first the tempo as an unsigned 32bit
4583 little-endian number, then pairs of unsigned 16bit little-endian numbers for
4584 pitch and duration pairs.
4586 If the arguments are a series of numbers, play the inline tune.
4588 The tempo is the base for all note durations. 60 gives a 1-second base, 120
4589 gives a half-second base, etc. Pitches are Hz. Set pitch to 0 to produce
4597 @deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device
4598 Retrieve device information. If option @option{--set} is given, assign result
4599 to variable @var{var}, otherwise print information on the screen.
4604 @subsection pxe_unload
4606 @deffn Command pxe_unload
4607 Unload the PXE environment (@pxref{Network}).
4609 This command is only available on PC BIOS systems.
4616 @deffn Command read [var]
4617 Read a line of input from the user. If an environment variable @var{var} is
4618 given, set that environment variable to the line of input that was read,
4619 with no terminating newline.
4626 @deffn Command reboot
4627 Reboot the computer.
4634 @deffn Command regexp [@option{--set} [number:]var] regexp string
4635 Test if regular expression @var{regexp} matches @var{string}. Supported
4636 regular expressions are POSIX.2 Extended Regular Expressions. If option
4637 @option{--set} is given, store @var{number}th matched subexpression in
4638 variable @var{var}. Subexpressions are numbered in order of their opening
4639 parentheses starting from @samp{1}. @var{number} defaults to @samp{1}.
4646 @deffn Command rmmod module
4647 Remove a loaded @var{module}.
4652 @subsection save_env
4654 @deffn Command save_env [@option{--file} file] var @dots{}
4655 Save the named variables from the environment to the environment block file.
4656 @xref{Environment block}.
4658 The @option{--file} option overrides the default location of the environment
4661 This command will operate successfully even when environment variable
4662 @code{check_signatures} is set to @code{enforce}
4663 (@pxref{check_signatures}), since it writes to disk and does not alter
4664 the behavior of GRUB based on any contents of disk that have been
4665 read. It is possible to modify a digitally signed environment block
4666 file from within GRUB using this command, such that its signature will
4667 no longer be valid on subsequent boots. Care should be taken in such
4668 advanced configurations to avoid rendering the system
4669 unbootable. @xref{Using digital signatures}, for more information.
4676 @deffn Command search @
4677 [@option{--file}|@option{--label}|@option{--fs-uuid}] @
4678 [@option{--set} [var]] [@option{--no-floppy}] name
4679 Search devices by file (@option{-f}, @option{--file}), filesystem label
4680 (@option{-l}, @option{--label}), or filesystem UUID (@option{-u},
4681 @option{--fs-uuid}).
4683 If the @option{--set} option is used, the first device found is set as the
4684 value of environment variable @var{var}. The default variable is
4687 The @option{--no-floppy} option prevents searching floppy devices, which can
4690 The @samp{search.file}, @samp{search.fs_label}, and @samp{search.fs_uuid}
4691 commands are aliases for @samp{search --file}, @samp{search --label}, and
4692 @samp{search --fs-uuid} respectively.
4699 @deffn Command sendkey @
4700 [@option{--num}|@option{--caps}|@option{--scroll}|@option{--insert}|@
4701 @option{--pause}|@option{--left-shift}|@option{--right-shift}|@
4702 @option{--sysrq}|@option{--numkey}|@option{--capskey}|@option{--scrollkey}|@
4703 @option{--insertkey}|@option{--left-alt}|@option{--right-alt}|@
4704 @option{--left-ctrl}|@option{--right-ctrl} @
4705 @samp{on}|@samp{off}]@dots{} @
4708 Insert keystrokes into the keyboard buffer when booting. Sometimes an
4709 operating system or chainloaded boot loader requires particular keys to be
4710 pressed: for example, one might need to press a particular key to enter
4711 "safe mode", or when chainloading another boot loader one might send
4712 keystrokes to it to navigate its menu.
4714 You may provide up to 16 keystrokes (the length of the BIOS keyboard
4715 buffer). Keystroke names may be upper-case or lower-case letters, digits,
4716 or taken from the following table:
4718 @c Please keep this table in the same order as in
4719 @c commands/i386/pc/sendkey.c, for ease of maintenance.
4720 @c Exception: The function and numeric keys are sorted, for aesthetics.
4722 @multitable @columnfractions .4 .5
4723 @headitem Name @tab Key
4724 @item escape @tab Escape
4727 @item numbersign @tab #
4729 @item percent @tab %
4731 @item ampersand @tab &
4732 @item asterisk @tab *
4733 @item parenleft @tab (
4734 @item parenright @tab )
4736 @item underscore @tab _
4739 @item backspace @tab Backspace
4741 @item bracketleft @tab [
4742 @item braceleft @tab @{
4743 @item bracketright @tab ]
4744 @item braceright @tab @}
4745 @item enter @tab Enter
4746 @item control @tab press and release Control
4747 @item semicolon @tab ;
4750 @item doublequote @tab "
4751 @item backquote @tab `
4753 @item shift @tab press and release left Shift
4754 @item backslash @tab \
4759 @item greater @tab >
4761 @item question @tab ?
4762 @item rshift @tab press and release right Shift
4763 @item alt @tab press and release Alt
4764 @item space @tab space bar
4765 @item capslock @tab Caps Lock
4778 @item num1 @tab 1 (numeric keypad)
4779 @item num2 @tab 2 (numeric keypad)
4780 @item num3 @tab 3 (numeric keypad)
4781 @item num4 @tab 4 (numeric keypad)
4782 @item num5 @tab 5 (numeric keypad)
4783 @item num6 @tab 6 (numeric keypad)
4784 @item num7 @tab 7 (numeric keypad)
4785 @item num8 @tab 8 (numeric keypad)
4786 @item num9 @tab 9 (numeric keypad)
4787 @item num0 @tab 0 (numeric keypad)
4788 @item numperiod @tab . (numeric keypad)
4789 @item numend @tab End (numeric keypad)
4790 @item numdown @tab Down (numeric keypad)
4791 @item numpgdown @tab Page Down (numeric keypad)
4792 @item numleft @tab Left (numeric keypad)
4793 @item numcenter @tab 5 with Num Lock inactive (numeric keypad)
4794 @item numright @tab Right (numeric keypad)
4795 @item numhome @tab Home (numeric keypad)
4796 @item numup @tab Up (numeric keypad)
4797 @item numpgup @tab Page Up (numeric keypad)
4798 @item numinsert @tab Insert (numeric keypad)
4799 @item numdelete @tab Delete (numeric keypad)
4800 @item numasterisk @tab * (numeric keypad)
4801 @item numminus @tab - (numeric keypad)
4802 @item numplus @tab + (numeric keypad)
4803 @item numslash @tab / (numeric keypad)
4804 @item numenter @tab Enter (numeric keypad)
4805 @item delete @tab Delete
4806 @item insert @tab Insert
4807 @item home @tab Home
4809 @item pgdown @tab Page Down
4810 @item pgup @tab Page Up
4811 @item down @tab Down
4813 @item left @tab Left
4814 @item right @tab Right
4817 As well as keystrokes, the @command{sendkey} command takes various options
4818 that affect the BIOS keyboard status flags. These options take an @samp{on}
4819 or @samp{off} parameter, specifying that the corresponding status flag be
4820 set or unset; omitting the option for a given status flag will leave that
4821 flag at its initial state at boot. The @option{--num}, @option{--caps},
4822 @option{--scroll}, and @option{--insert} options emulate setting the
4823 corresponding mode, while the @option{--numkey}, @option{--capskey},
4824 @option{--scrollkey}, and @option{--insertkey} options emulate pressing and
4825 holding the corresponding key. The other status flag options are
4828 If the @option{--no-led} option is given, the status flag options will have
4829 no effect on keyboard LEDs.
4831 If the @command{sendkey} command is given multiple times, then only the last
4832 invocation has any effect.
4834 Since @command{sendkey} manipulates the BIOS keyboard buffer, it may cause
4835 hangs, reboots, or other misbehaviour on some systems. If the operating
4836 system or boot loader that runs after GRUB uses its own keyboard driver
4837 rather than the BIOS keyboard functions, then @command{sendkey} will have no
4840 This command is only available on PC BIOS systems.
4847 @deffn Command set [envvar=value]
4848 Set the environment variable @var{envvar} to @var{value}. If invoked with no
4849 arguments, print all environment variables with their values.
4856 @deffn Command sha1sum arg @dots{}
4857 Alias for @code{hashsum --hash sha1 arg @dots{}}. See command @command{hashsum}
4858 (@pxref{hashsum}) for full description.
4863 @subsection sha256sum
4865 @deffn Command sha256sum arg @dots{}
4866 Alias for @code{hashsum --hash sha256 arg @dots{}}. See command @command{hashsum}
4867 (@pxref{hashsum}) for full description.
4872 @subsection sha512sum
4874 @deffn Command sha512sum arg @dots{}
4875 Alias for @code{hashsum --hash sha512 arg @dots{}}. See command @command{hashsum}
4876 (@pxref{hashsum}) for full description.
4883 @deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
4884 Sleep for @var{count} seconds. If option @option{--interruptible} is given,
4885 allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
4886 of remaining seconds.
4893 @deffn Command source file
4894 Read @var{file} as a configuration file, as if its contents had been
4895 incorporated directly into the sourcing file. Unlike @command{configfile}
4896 (@pxref{configfile}), this executes the contents of @var{file} without
4897 changing context: any environment variable changes made by the commands in
4898 @var{file} will be preserved after @command{source} returns, and the menu
4899 will not be shown immediately.
4906 @deffn Command test expression
4907 Evaluate @var{expression} and return zero exit status if result is true,
4908 non zero status otherwise.
4910 @var{expression} is one of:
4913 @item @var{string1} @code{==} @var{string2}
4914 the strings are equal
4915 @item @var{string1} @code{!=} @var{string2}
4916 the strings are not equal
4917 @item @var{string1} @code{<} @var{string2}
4918 @var{string1} is lexicographically less than @var{string2}
4919 @item @var{string1} @code{<=} @var{string2}
4920 @var{string1} is lexicographically less or equal than @var{string2}
4921 @item @var{string1} @code{>} @var{string2}
4922 @var{string1} is lexicographically greater than @var{string2}
4923 @item @var{string1} @code{>=} @var{string2}
4924 @var{string1} is lexicographically greater or equal than @var{string2}
4925 @item @var{integer1} @code{-eq} @var{integer2}
4926 @var{integer1} is equal to @var{integer2}
4927 @item @var{integer1} @code{-ge} @var{integer2}
4928 @var{integer1} is greater than or equal to @var{integer2}
4929 @item @var{integer1} @code{-gt} @var{integer2}
4930 @var{integer1} is greater than @var{integer2}
4931 @item @var{integer1} @code{-le} @var{integer2}
4932 @var{integer1} is less than or equal to @var{integer2}
4933 @item @var{integer1} @code{-lt} @var{integer2}
4934 @var{integer1} is less than @var{integer2}
4935 @item @var{integer1} @code{-ne} @var{integer2}
4936 @var{integer1} is not equal to @var{integer2}
4937 @item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2}
4938 @var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}.
4939 @item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2}
4940 @var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}.
4941 @item @var{file1} @code{-nt} @var{file2}
4942 @var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time.
4943 @item @var{file1} @code{-ot} @var{file2}
4944 @var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time.
4945 @item @code{-d} @var{file}
4946 @var{file} exists and is a directory
4947 @item @code{-e} @var{file}
4949 @item @code{-f} @var{file}
4950 @var{file} exists and is not a directory
4951 @item @code{-s} @var{file}
4952 @var{file} exists and has a size greater than zero
4953 @item @code{-n} @var{string}
4954 the length of @var{string} is nonzero
4956 @var{string} is equivalent to @code{-n @var{string}}
4957 @item @code{-z} @var{string}
4958 the length of @var{string} is zero
4959 @item @code{(} @var{expression} @code{)}
4960 @var{expression} is true
4961 @item @code{!} @var{expression}
4962 @var{expression} is false
4963 @item @var{expression1} @code{-a} @var{expression2}
4964 both @var{expression1} and @var{expression2} are true
4965 @item @var{expression1} @code{-o} @var{expression2}
4966 either @var{expression1} or @var{expression2} is true
4975 Do nothing, successfully. This is mainly useful in control constructs such
4976 as @code{if} and @code{while} (@pxref{Shell-like scripting}).
4982 @deffn Command trust [@option{--skip-sig}] pubkey_file
4983 Read public key from @var{pubkey_file} and add it to GRUB's internal
4984 list of trusted public keys. These keys are used to validate digital
4985 signatures when environment variable @code{check_signatures} is set to
4986 @code{enforce}. Note that if @code{check_signatures} is set to
4987 @code{enforce} when @command{trust} executes, then @var{pubkey_file}
4988 must itself be properly signed. The @option{--skip-sig} option can be
4989 used to disable signature-checking when reading @var{pubkey_file}
4990 itself. It is expected that @option{--skip-sig} is useful for testing
4991 and manual booting. @xref{Using digital signatures}, for more
4999 @deffn Command unset envvar
5000 Unset the environment variable @var{envvar}.
5005 @subsection uppermem
5007 This command is not yet implemented for GRUB 2, although it is planned.
5014 @deffn Command vbeinfo [[WxH]xD]
5015 Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available
5016 only on PC BIOS platforms.
5021 @node verify_detached
5022 @subsection verify_detached
5024 @deffn Command verify_detached [@option{--skip-sig}] file signature_file [pubkey_file]
5025 Verifies a GPG-style detached signature, where the signed file is
5026 @var{file}, and the signature itself is in file @var{signature_file}.
5027 Optionally, a specific public key to use can be specified using
5028 @var{pubkey_file}. When environment variable @code{check_signatures}
5029 is set to @code{enforce}, then @var{pubkey_file} must itself be
5030 properly signed by an already-trusted key. An unsigned
5031 @var{pubkey_file} can be loaded by specifying @option{--skip-sig}.
5032 If @var{pubkey_file} is omitted, then public keys from GRUB's trusted keys
5033 (@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}) are
5036 Exit code @code{$?} is set to 0 if the signature validates
5037 successfully. If validation fails, it is set to a non-zero value.
5038 @xref{Using digital signatures}, for more information.
5042 @subsection videoinfo
5044 @deffn Command videoinfo [[WxH]xD]
5045 List available video modes. If resolution is given, show only matching modes.
5048 @node Networking commands
5049 @section The list of networking commands
5052 * net_add_addr:: Add a network address
5053 * net_add_dns:: Add a DNS server
5054 * net_add_route:: Add routing entry
5055 * net_bootp:: Perform a bootp autoconfiguration
5056 * net_del_addr:: Remove IP address from interface
5057 * net_del_dns:: Remove a DNS server
5058 * net_del_route:: Remove a route entry
5059 * net_get_dhcp_option:: Retrieve DHCP options
5060 * net_ipv6_autoconf:: Perform IPv6 autoconfiguration
5061 * net_ls_addr:: List interfaces
5062 * net_ls_cards:: List network cards
5063 * net_ls_dns:: List DNS servers
5064 * net_ls_routes:: List routing entries
5065 * net_nslookup:: Perform a DNS lookup
5070 @subsection net_add_addr
5072 @deffn Command net_add_addr @var{interface} @var{card} @var{address}
5073 Configure additional network @var{interface} with @var{address} on a
5074 network @var{card}. @var{address} can be either IP in dotted decimal notation,
5075 or symbolic name which is resolved using DNS lookup. If successful, this command
5076 also adds local link routing entry to the default subnet of @var{address}
5077 with name @var{interface}@samp{:local} via @var{interface}.
5082 @subsection net_add_dns
5084 @deffn Command net_add_dns @var{server}
5085 Resolve @var{server} IP address and add to the list of DNS servers used during
5091 @subsection net_add_route
5093 @deffn Command net_add_route @var{shortname} @var{ip}[/@var{prefix}] [@var{interface} | @samp{gw} @var{gateway}]
5094 Add route to network with address @var{ip} as modified by @var{prefix} via
5095 either local @var{interface} or @var{gateway}. @var{prefix} is optional and
5096 defaults to 32 for IPv4 address and 128 for IPv6 address. Route is identified
5097 by @var{shortname} which can be used to remove it (@pxref{net_del_route}).
5102 @subsection net_bootp
5104 @deffn Command net_bootp [@var{card}]
5105 Perform configuration of @var{card} using DHCP protocol. If no card name
5106 is specified, try to configure all existing cards. If configuration was
5107 successful, interface with name @var{card}@samp{:dhcp} and configured
5108 address is added to @var{card}. If server provided gateway information in
5109 DHCP ACK packet, it is added as route entry with the name @var{card}@samp{:dhcp:gw}. Additionally the following DHCP options are recognized and processed:
5112 @item 1 (Subnet Mask)
5113 Used to calculate network local routing entry for interface @var{card}@samp{:dhcp}.
5115 Adds default route entry with the name @var{card}@samp{:dhcp:default} via gateway
5116 from DHCP option. Note that only option with single route is accepted.
5117 @item 6 (Domain Name Server)
5118 Adds all servers from option value to the list of servers used during name resolution.
5119 @item 12 (Host Name)
5120 Sets environment variable @samp{net_}@var{<card>}@samp{_dhcp_hostname}
5121 (@pxref{net_@var{<interface>}_hostname}) to the value of option.
5122 @item 15 (Domain Name)
5123 Sets environment variable @samp{net_}@var{<card>}@samp{_dhcp_domain}
5124 (@pxref{net_@var{<interface>}_domain}) to the value of option.
5125 @item 17 (Root Path)
5126 Sets environment variable @samp{net_}@var{<card>}@samp{_dhcp_rootpath}
5127 (@pxref{net_@var{<interface>}_rootpath}) to the value of option.
5128 @item 18 (Extensions Path)
5129 Sets environment variable @samp{net_}@var{<card>}@samp{_dhcp_extensionspath}
5130 (@pxref{net_@var{<interface>}_extensionspath}) to the value of option.
5137 @subsection net_del_addr
5139 @deffn Command net_del_addr @var{interface}
5140 Remove configured @var{interface} with associated address.
5145 @subsection net_del_dns
5147 @deffn Command net_del_dns @var{address}
5148 Remove @var{address} from list of servers used during name lookup.
5153 @subsection net_del_route
5155 @deffn Command net_del_route @var{shortname}
5156 Remove route entry identified by @var{shortname}.
5160 @node net_get_dhcp_option
5161 @subsection net_get_dhcp_option
5163 @deffn Command net_get_dhcp_option @var{var} @var{interface} @var{number} @var{type}
5164 Request DHCP option @var{number} of @var{type} via @var{interface}. @var{type}
5165 can be one of @samp{string}, @samp{number} or @samp{hex}. If option is found,
5166 assign its value to variable @var{var}. Values of types @samp{number} and @samp{hex}
5167 are converted to string representation.
5171 @node net_ipv6_autoconf
5172 @subsection net_ipv6_autoconf
5174 @deffn Command net_ipv6_autoconf [@var{card}]
5175 Perform IPv6 autoconfiguration by adding to the @var{card} interface with name
5176 @var{card}@samp{:link} and link local MAC-based address. If no card is specified,
5177 perform autoconfiguration for all existing cards.
5182 @subsection net_ls_addr
5184 @deffn Command net_ls_addr
5185 List all configured interfaces with their MAC and IP addresses.
5190 @subsection net_ls_cards
5192 @deffn Command net_ls_cards
5193 List all detected network cards with their MAC address.
5198 @subsection net_ls_dns
5200 @deffn Command net_ls_dns
5201 List addresses of DNS servers used during name lookup.
5206 @subsection net_ls_routes
5208 @deffn Command net_ls_routes
5209 List routing entries.
5214 @subsection net_nslookup
5216 @deffn Command net_nslookup @var{name} [@var{server}]
5217 Resolve address of @var{name} using DNS server @var{server}. If no server
5218 is given, use default list of servers.
5222 @node Internationalisation
5223 @chapter Internationalisation
5226 GRUB uses UTF-8 internally other than in rendering where some GRUB-specific
5227 appropriate representation is used. All text files (including config) are
5228 assumed to be encoded in UTF-8.
5230 @section Filesystems
5231 NTFS, JFS, UDF, HFS+, exFAT, long filenames in FAT, Joliet part of
5232 ISO9660 are treated as UTF-16 as per specification. AFS and BFS are read
5233 as UTF-8, again according to specification. BtrFS, cpio, tar, squash4, minix,
5234 minix2, minix3, ROMFS, ReiserFS, XFS, ext2, ext3, ext4, FAT (short names),
5235 RockRidge part of ISO9660, nilfs2, UFS1, UFS2 and ZFS are assumed
5236 to be UTF-8. This might be false on systems configured with legacy charset
5237 but as long as the charset used is superset of ASCII you should be able to
5238 access ASCII-named files. And it's recommended to configure your system to use
5239 UTF-8 to access the filesystem, convmv may help with migration. ISO9660 (plain)
5240 filenames are specified as being ASCII or being described with unspecified
5241 escape sequences. GRUB assumes that the ISO9660 names are UTF-8 (since
5242 any ASCII is valid UTF-8). There are some old CD-ROMs which use CP437
5243 in non-compliant way. You're still able to access files with names containing
5244 only ASCII characters on such filesystems though. You're also able to access
5245 any file if the filesystem contains valid Joliet (UTF-16) or RockRidge (UTF-8).
5246 AFFS, SFS and HFS never use unicode and GRUB assumes them to be in Latin1,
5247 Latin1 and MacRoman respectively. GRUB handles filesystem case-insensitivity
5248 however no attempt is performed at case conversion of international characters
5249 so e.g. a file named lowercase greek alpha is treated as different from
5250 the one named as uppercase alpha. The filesystems in questions are
5251 NTFS (except POSIX namespace), HFS+ (configurable at mkfs time, default
5252 insensitive), SFS (configurable at mkfs time, default insensitive),
5253 JFS (configurable at mkfs time, default sensitive), HFS, AFFS, FAT, exFAT
5254 and ZFS (configurable on per-subvolume basis by property ``casesensitivity'',
5255 default sensitive). On ZFS subvolumes marked as case insensitive files
5256 containing lowercase international characters are inaccessible.
5257 Also like all supported filesystems except HFS+ and ZFS (configurable on
5258 per-subvolume basis by property ``normalization'', default none) GRUB makes
5259 no attempt at check of canonical equivalence so a file name u-diaresis is
5260 treated as distinct from u+combining diaresis. This however means that in
5261 order to access file on HFS+ its name must be specified in normalisation form D.
5262 On normalized ZFS subvolumes filenames out of normalisation are inaccessible.
5264 @section Output terminal
5265 Firmware output console ``console'' on ARC and IEEE1275 are limited to ASCII.
5267 BIOS firmware console and VGA text are limited to ASCII and some pseudographics.
5269 None of above mentioned is appropriate for displaying international and any
5270 unsupported character is replaced with question mark except pseudographics
5271 which we attempt to approximate with ASCII.
5273 EFI console on the other hand nominally supports UTF-16 but actual language
5274 coverage depends on firmware and may be very limited.
5276 The encoding used on serial can be chosen with @command{terminfo} as
5277 either ASCII, UTF-8 or ``visual UTF-8''. Last one is against the specification
5278 but results in correct rendering of right-to-left on some readers which don't
5279 have own bidi implementation.
5281 On emu GRUB checks if charset is UTF-8 and uses it if so and uses ASCII
5284 When using gfxterm or gfxmenu GRUB itself is responsible for rendering the
5285 text. In this case GRUB is limited by loaded fonts. If fonts contain all
5286 required characters then bidirectional text, cursive variants and combining
5287 marks other than enclosing, half (e.g. left half tilde or combining overline)
5288 and double ones. Ligatures aren't supported though. This should cover European,
5289 Middle Eastern (if you don't mind lack of lam-alif ligature in Arabic) and
5290 East Asian scripts. Notable unsupported scripts are Brahmic family and
5291 derived as well as Mongolian, Tifinagh, Korean Jamo (precomposed characters
5292 have no problem) and tonal writing (2e5-2e9). GRUB also ignores deprecated
5293 (as specified in Unicode) characters (e.g. tags). GRUB also doesn't handle so
5294 called ``annotation characters'' If you can complete either of
5295 two lists or, better, propose a patch to improve rendering, please contact
5298 @section Input terminal
5299 Firmware console on BIOS, IEEE1275 and ARC doesn't allow you to enter non-ASCII
5300 characters. EFI specification allows for such but author is unaware of any
5301 actual implementations. Serial input is currently limited for latin1 (unlikely
5302 to change). Own keyboard implementations (at_keyboard and usb_keyboard)
5303 supports any key but work on one-char-per-keystroke.
5304 So no dead keys or advanced input method. Also there is no keymap change hotkey.
5305 In practice it makes difficult to enter any text using non-Latin alphabet.
5306 Moreover all current input consumers are limited to ASCII.
5309 GRUB supports being translated. For this you need to have language *.mo files in $prefix/locale, load gettext module and set ``lang'' variable.
5312 Regexps work on unicode characters, however no attempt at checking cannonical
5313 equivalence has been made. Moreover the classes like [:alpha:] match only
5317 Currently GRUB always uses YEAR-MONTH-DAY HOUR:MINUTE:SECOND [WEEKDAY] 24-hour
5318 datetime format but weekdays are translated.
5319 GRUB always uses the decimal number format with [0-9] as digits and . as
5320 descimal separator and no group separator.
5321 IEEE1275 aliases are matched case-insensitively except non-ASCII which is
5322 matched as binary. Similar behaviour is for matching OSBundleRequired.
5323 Since IEEE1275 aliases and OSBundleRequired don't contain any non-ASCII it
5324 should never be a problem in practice.
5325 Case-sensitive identifiers are matched as raw strings, no canonical
5326 equivalence check is performed. Case-insenstive identifiers are matched
5327 as RAW but additionally [a-z] is equivalent to [A-Z]. GRUB-defined
5328 identifiers use only ASCII and so should user-defined ones.
5329 Identifiers containing non-ASCII may work but aren't supported.
5330 Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
5331 LF U+000a) are recognised. Other unicode space characters aren't a valid
5333 @command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the
5334 lexicographical order of unicode codepoints, replicating the behaviour of
5335 test from coreutils.
5336 environment variables and commands are listed in the same order.
5342 * Authentication and authorisation:: Users and access control
5343 * Using digital signatures:: Booting digitally signed code
5346 @node Authentication and authorisation
5347 @section Authentication and authorisation in GRUB
5349 By default, the boot loader interface is accessible to anyone with physical
5350 access to the console: anyone can select and edit any menu entry, and anyone
5351 can get direct access to a GRUB shell prompt. For most systems, this is
5352 reasonable since anyone with direct physical access has a variety of other
5353 ways to gain full access, and requiring authentication at the boot loader
5354 level would only serve to make it difficult to recover broken systems.
5356 However, in some environments, such as kiosks, it may be appropriate to lock
5357 down the boot loader to require authentication before performing certain
5360 The @samp{password} (@pxref{password}) and @samp{password_pbkdf2}
5361 (@pxref{password_pbkdf2}) commands can be used to define users, each of
5362 which has an associated password. @samp{password} sets the password in
5363 plain text, requiring @file{grub.cfg} to be secure; @samp{password_pbkdf2}
5364 sets the password hashed using the Password-Based Key Derivation Function
5365 (RFC 2898), requiring the use of @command{grub-mkpasswd-pbkdf2}
5366 (@pxref{Invoking grub-mkpasswd-pbkdf2}) to generate password hashes.
5368 In order to enable authentication support, the @samp{superusers} environment
5369 variable must be set to a list of usernames, separated by any of spaces,
5370 commas, semicolons, pipes, or ampersands. Superusers are permitted to use
5371 the GRUB command line, edit menu entries, and execute any menu entry. If
5372 @samp{superusers} is set, then use of the command line is automatically
5373 restricted to superusers.
5375 Other users may be given access to specific menu entries by giving a list of
5376 usernames (as above) using the @option{--users} option to the
5377 @samp{menuentry} command (@pxref{menuentry}). If the @option{--unrestricted}
5378 option is used for a menu entry, then that entry is unrestricted.
5379 If the @option{--users} option is not used for a menu entry, then that
5380 only superusers are able to use it.
5382 Putting this together, a typical @file{grub.cfg} fragment might look like
5387 set superusers="root"
5388 password_pbkdf2 root grub.pbkdf2.sha512.10000.biglongstring
5389 password user1 insecure
5391 menuentry "May be run by any user" --unrestricted @{
5396 menuentry "Superusers only" --users "" @{
5398 linux /vmlinuz single
5401 menuentry "May be run by user1 or a superuser" --users user1 @{
5408 The @command{grub-mkconfig} program does not yet have built-in support for
5409 generating configuration files with authentication. You can use
5410 @file{/etc/grub.d/40_custom} to add simple superuser authentication, by
5411 adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
5414 @node Using digital signatures
5415 @section Using digital signatures in GRUB
5417 GRUB's @file{core.img} can optionally provide enforcement that all files
5418 subsequently read from disk are covered by a valid digital signature.
5419 This document does @strong{not} cover how to ensure that your
5420 platform's firmware (e.g., Coreboot) validates @file{core.img}.
5422 If environment variable @code{check_signatures}
5423 (@pxref{check_signatures}) is set to @code{enforce}, then every
5424 attempt by the GRUB @file{core.img} to load another file @file{foo}
5425 implicitly invokes @code{verify_detached foo foo.sig}
5426 (@pxref{verify_detached}). @code{foo.sig} must contain a valid
5427 digital signature over the contents of @code{foo}, which can be
5428 verified with a public key currently trusted by GRUB
5429 (@pxref{list_trusted}, @pxref{trust}, and @pxref{distrust}). If
5430 validation fails, then file @file{foo} cannot be opened. This failure
5431 may halt or otherwise impact the boot process.
5433 @comment Unfortunately --pubkey is not yet supported by grub-install,
5434 @comment but we should not bring up internal detail grub-mkimage here
5435 @comment in the user guide (as opposed to developer's manual).
5437 @comment An initial trusted public key can be embedded within the GRUB
5438 @comment @file{core.img} using the @code{--pubkey} option to
5439 @comment @command{grub-mkimage} (@pxref{Invoking grub-install}). Presently it
5440 @comment is necessary to write a custom wrapper around @command{grub-mkimage}
5441 @comment using the @code{--grub-mkimage} flag to @command{grub-install}.
5443 GRUB uses GPG-style detached signatures (meaning that a file
5444 @file{foo.sig} will be produced when file @file{foo} is signed), and
5445 currently supports the DSA and RSA signing algorithms. A signing key
5446 can be generated as follows:
5452 An individual file can be signed as follows:
5455 gpg --detach-sign /path/to/file
5458 For successful validation of all of GRUB's subcomponents and the
5459 loaded OS kernel, they must all be signed. One way to accomplish this
5460 is the following (after having already produced the desired
5461 @file{grub.cfg} file, e.g., by running @command{grub-mkconfig}
5462 (@pxref{Invoking grub-mkconfig}):
5466 # Edit /dev/shm/passphrase.txt to contain your signing key's passphrase
5467 for i in `find /boot -name "*.cfg" -or -name "*.lst" -or \
5468 -name "*.mod" -or -name "vmlinuz*" -or -name "initrd*" -or \
5471 gpg --batch --detach-sign --passphrase-fd 0 $i < \
5472 /dev/shm/passphrase.txt
5474 shred /dev/shm/passphrase.txt
5478 See also: @ref{check_signatures}, @ref{verify_detached}, @ref{trust},
5479 @ref{list_trusted}, @ref{distrust}, @ref{load_env}, @ref{save_env}.
5481 Note that internally signature enforcement is controlled by setting
5482 the environment variable @code{check_signatures} equal to
5483 @code{enforce}. Passing one or more @code{--pubkey} options to
5484 @command{grub-mkimage} implicitly defines @code{check_signatures}
5485 equal to @code{enforce} in @file{core.img} prior to processing any
5486 configuration files.
5488 Note that signature checking does @strong{not} prevent an attacker
5489 with (serial, physical, ...) console access from dropping manually to
5490 the GRUB console and executing:
5493 set check_signatures=no
5496 To prevent this, password-protection (@pxref{Authentication and
5497 authorisation}) is essential. Note that even with GRUB password
5498 protection, GRUB itself cannot prevent someone with physical access to
5499 the machine from altering that machine's firmware (e.g., Coreboot
5500 or BIOS) configuration to cause the machine to boot from a different
5501 (attacker-controlled) device. GRUB is at best only one link in a
5504 @node Platform limitations
5505 @chapter Platform limitations
5507 GRUB2 is designed to be portable and is actually ported across platforms. We
5508 try to keep all platforms at the level. Unfortunately some platforms are better
5509 supported than others. This is detailed in current and 2 following sections.
5511 ARC platform is unable to change datetime (firmware doesn't seem to provide a
5513 EMU has similar limitation.
5515 On EMU platform no serial port is available.
5517 Console charset refers only to firmware-assisted console. gfxterm is always
5518 Unicode (see Internationalisation section for its limitations). Serial is
5519 configurable to UTF-8 or ASCII (see Internationalisation). In case of qemu
5520 and coreboot ports the refered console is vga_text. Loongson always uses
5523 Most limited one is ASCII. CP437 provides additionally pseudographics.
5524 GRUB2 doesn't use any language characters from CP437 as often CP437 is replaced
5525 by national encoding compatible only in pseudographics.
5526 Unicode is the most versatile charset which supports many languages. However
5527 the actual console may be much more limited depending on firmware
5529 On BIOS network is supported only if the image is loaded through network.
5530 On sparc64 GRUB is unable to determine which server it was booted from.
5532 Direct ATA/AHCI support allows to circumvent various firmware limitations but
5533 isn't needed for normal operation except on baremetal ports.
5535 AT keyboard support allows keyboard layout remapping and support for keys not
5536 available through firmware. It isn't needed for normal operation except
5539 Speaker allows morse and spkmodem communication.
5541 USB support provides benefits similar to ATA (for USB disks) or AT (for USB
5542 keyboards). In addition it allows USBserial.
5544 Chainloading refers to the ability to load another bootloader through the same protocol
5546 Hints allow faster disk discovery by already knowing in advance which is the disk in
5547 question. On some platforms hints are correct unless you move the disk between boots.
5548 On other platforms it's just an educated guess.
5549 Note that hint failure results in just reduced performance, not a failure
5551 BadRAM is the ability to mark some of the RAM as ``bad''. Note: due to protocol
5552 limitations mips-loongson (with Linux protocol)
5553 and mips-qemu_mips can use only memory up to first hole.
5555 @multitable @columnfractions .20 .20 .20 .20 .20
5556 @item @tab BIOS @tab Coreboot @tab Multiboot @tab Qemu
5557 @item video @tab yes @tab yes @tab yes @tab yes
5558 @item console charset @tab CP437 @tab CP437 @tab CP437 @tab CP437
5559 @item network @tab yes (*) @tab no @tab no @tab no
5560 @item ATA/AHCI @tab yes @tab yes @tab yes @tab yes
5561 @item AT keyboard @tab yes @tab yes @tab yes @tab yes
5562 @item Speaker @tab yes @tab yes @tab yes @tab yes
5563 @item USB @tab yes @tab yes @tab yes @tab yes
5564 @item chainloader @tab local @tab yes @tab yes @tab no
5565 @item cpuid @tab partial @tab partial @tab partial @tab partial
5566 @item hints @tab guess @tab guess @tab guess @tab guess
5567 @item PCI @tab yes @tab yes @tab yes @tab yes
5568 @item badram @tab yes @tab yes @tab yes @tab yes
5569 @item compression @tab always @tab pointless @tab no @tab no
5570 @item exit @tab yes @tab no @tab no @tab no
5573 @multitable @columnfractions .20 .20 .20 .20 .20
5574 @item @tab ia32 EFI @tab amd64 EFI @tab ia32 IEEE1275 @tab Itanium
5575 @item video @tab yes @tab yes @tab no @tab no
5576 @item console charset @tab Unicode @tab Unicode @tab ASCII @tab Unicode
5577 @item network @tab yes @tab yes @tab yes @tab yes
5578 @item ATA/AHCI @tab yes @tab yes @tab yes @tab no
5579 @item AT keyboard @tab yes @tab yes @tab yes @tab no
5580 @item Speaker @tab yes @tab yes @tab yes @tab no
5581 @item USB @tab yes @tab yes @tab yes @tab no
5582 @item chainloader @tab local @tab local @tab no @tab local
5583 @item cpuid @tab partial @tab partial @tab partial @tab no
5584 @item hints @tab guess @tab guess @tab good @tab guess
5585 @item PCI @tab yes @tab yes @tab yes @tab no
5586 @item badram @tab yes @tab yes @tab no @tab yes
5587 @item compression @tab no @tab no @tab no @tab no
5588 @item exit @tab yes @tab yes @tab yes @tab yes
5591 @multitable @columnfractions .20 .20 .20 .20 .20
5592 @item @tab Loongson @tab sparc64 @tab Powerpc @tab ARC
5593 @item video @tab yes @tab no @tab yes @tab no
5594 @item console charset @tab N/A @tab ASCII @tab ASCII @tab ASCII
5595 @item network @tab no @tab yes (*) @tab yes @tab no
5596 @item ATA/AHCI @tab yes @tab no @tab no @tab no
5597 @item AT keyboard @tab yes @tab no @tab no @tab no
5598 @item Speaker @tab no @tab no @tab no @tab no
5599 @item USB @tab yes @tab no @tab no @tab no
5600 @item chainloader @tab yes @tab no @tab no @tab no
5601 @item cpuid @tab no @tab no @tab no @tab no
5602 @item hints @tab good @tab good @tab good @tab no
5603 @item PCI @tab yes @tab no @tab no @tab no
5604 @item badram @tab yes (*) @tab no @tab no @tab no
5605 @item compression @tab configurable @tab no @tab no @tab configurable
5606 @item exit @tab no @tab yes @tab yes @tab yes
5609 @multitable @columnfractions .20 .20 .20 .20 .20
5610 @item @tab MIPS qemu @tab emu
5611 @item video @tab no @tab yes
5612 @item console charset @tab CP437 @tab Unicode (*)
5613 @item network @tab no @tab yes
5614 @item ATA/AHCI @tab yes @tab no
5615 @item AT keyboard @tab yes @tab no
5616 @item Speaker @tab no @tab no
5617 @item USB @tab N/A @tab yes
5618 @item chainloader @tab yes @tab no
5619 @item cpuid @tab no @tab no
5620 @item hints @tab guess @tab no
5621 @item PCI @tab no @tab no
5622 @item badram @tab yes (*) @tab no
5623 @item compression @tab configurable @tab no
5624 @item exit @tab no @tab yes
5627 @node Platform-specific operations
5630 Some platforms have features which allows to implement
5631 some commands useless or not implementable on others.
5635 Information retrieval:
5638 @item mipsel-loongson: lsspd
5639 @item mips-arc: lsdev
5640 @item efi: lsefisystab, lssal, lsefimmap, lsefi
5641 @item i386-pc: lsapm
5642 @item i386-coreboot: lscoreboot, coreboot_boottime, cbmemc
5643 @item acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi): lsacpi
5646 Workarounds for platform-specific issues:
5648 @item i386-efi/x86_64-efi: loadbios, fakebios, fix_video
5649 @item acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi):
5650 acpi (override ACPI tables)
5651 @item i386-pc: drivemap
5652 @item i386-pc: sendkey
5655 Advanced operations for power users:
5657 @item x86: iorw (direct access to I/O ports)
5662 @item cmos (x86-*, ieee1275, mips-qemu_mips, mips-loongson): cmostest
5663 (used on some laptops to check for special power-on key), cmosclean
5667 @node Supported kernels
5668 @chapter Supported boot targets
5670 X86 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.
5671 @multitable @columnfractions .50 .22 .22
5672 @item @tab BIOS @tab Coreboot
5673 @item BIOS chainloading @tab yes @tab no (1)
5674 @item NTLDR @tab yes @tab no (1)
5675 @item Plan9 @tab yes @tab no (1)
5676 @item Freedos @tab yes @tab no (1)
5677 @item FreeBSD bootloader @tab yes @tab crashes (1)
5678 @item 32-bit kFreeBSD @tab yes @tab crashes (5)
5679 @item 64-bit kFreeBSD @tab yes @tab crashes (5)
5680 @item 32-bit kNetBSD @tab yes @tab crashes (1)
5681 @item 64-bit kNetBSD @tab yes @tab crashes
5682 @item 32-bit kOpenBSD @tab yes @tab yes
5683 @item 64-bit kOpenBSD @tab yes @tab yes
5684 @item Multiboot @tab yes @tab yes
5685 @item Multiboot2 @tab yes @tab yes
5686 @item 32-bit Linux (legacy protocol) @tab yes @tab no (1)
5687 @item 64-bit Linux (legacy protocol) @tab yes @tab no (1)
5688 @item 32-bit Linux (modern protocol) @tab yes @tab yes
5689 @item 64-bit Linux (modern protocol) @tab yes @tab yes
5690 @item 32-bit XNU @tab yes @tab ?
5691 @item 64-bit XNU @tab yes @tab ?
5692 @item 32-bit EFI chainloader @tab no (2) @tab no (2)
5693 @item 64-bit EFI chainloader @tab no (2) @tab no (2)
5694 @item Appleloader @tab no (2) @tab no (2)
5697 @multitable @columnfractions .50 .22 .22
5698 @item @tab Multiboot @tab Qemu
5699 @item BIOS chainloading @tab no (1) @tab no (1)
5700 @item NTLDR @tab no (1) @tab no (1)
5701 @item Plan9 @tab no (1) @tab no (1)
5702 @item FreeDOS @tab no (1) @tab no (1)
5703 @item FreeBSD bootloader @tab crashes (1) @tab crashes (1)
5704 @item 32-bit kFreeBSD @tab crashes (5) @tab crashes (5)
5705 @item 64-bit kFreeBSD @tab crashes (5) @tab crashes (5)
5706 @item 32-bit kNetBSD @tab crashes (1) @tab crashes (1)
5707 @item 64-bit kNetBSD @tab yes @tab yes
5708 @item 32-bit kOpenBSD @tab yes @tab yes
5709 @item 64-bit kOpenBSD @tab yes @tab yes
5710 @item Multiboot @tab yes @tab yes
5711 @item Multiboot2 @tab yes @tab yes
5712 @item 32-bit Linux (legacy protocol) @tab no (1) @tab no (1)
5713 @item 64-bit Linux (legacy protocol) @tab no (1) @tab no (1)
5714 @item 32-bit Linux (modern protocol) @tab yes @tab yes
5715 @item 64-bit Linux (modern protocol) @tab yes @tab yes
5716 @item 32-bit XNU @tab ? @tab ?
5717 @item 64-bit XNU @tab ? @tab ?
5718 @item 32-bit EFI chainloader @tab no (2) @tab no (2)
5719 @item 64-bit EFI chainloader @tab no (2) @tab no (2)
5720 @item Appleloader @tab no (2) @tab no (2)
5723 @multitable @columnfractions .50 .22 .22
5724 @item @tab ia32 EFI @tab amd64 EFI
5725 @item BIOS chainloading @tab no (1) @tab no (1)
5726 @item NTLDR @tab no (1) @tab no (1)
5727 @item Plan9 @tab no (1) @tab no (1)
5728 @item FreeDOS @tab no (1) @tab no (1)
5729 @item FreeBSD bootloader @tab crashes (1) @tab crashes (1)
5730 @item 32-bit kFreeBSD @tab headless @tab headless
5731 @item 64-bit kFreeBSD @tab headless @tab headless
5732 @item 32-bit kNetBSD @tab crashes (1) @tab crashes (1)
5733 @item 64-bit kNetBSD @tab yes @tab yes
5734 @item 32-bit kOpenBSD @tab headless @tab headless
5735 @item 64-bit kOpenBSD @tab headless @tab headless
5736 @item Multiboot @tab yes @tab yes
5737 @item Multiboot2 @tab yes @tab yes
5738 @item 32-bit Linux (legacy protocol) @tab no (1) @tab no (1)
5739 @item 64-bit Linux (legacy protocol) @tab no (1) @tab no (1)
5740 @item 32-bit Linux (modern protocol) @tab yes @tab yes
5741 @item 64-bit Linux (modern protocol) @tab yes @tab yes
5742 @item 32-bit XNU @tab yes @tab yes
5743 @item 64-bit XNU @tab yes (4) @tab yes
5744 @item 32-bit EFI chainloader @tab yes @tab no (3)
5745 @item 64-bit EFI chainloader @tab no (3) @tab yes
5746 @item Appleloader @tab yes @tab yes
5749 @multitable @columnfractions .50 .22 .22
5750 @item @tab ia32 IEEE1275
5751 @item BIOS chainloading @tab no (1)
5752 @item NTLDR @tab no (1)
5753 @item Plan9 @tab no (1)
5754 @item FreeDOS @tab no (1)
5755 @item FreeBSD bootloader @tab crashes (1)
5756 @item 32-bit kFreeBSD @tab crashes (5)
5757 @item 64-bit kFreeBSD @tab crashes (5)
5758 @item 32-bit kNetBSD @tab crashes (1)
5759 @item 64-bit kNetBSD @tab ?
5760 @item 32-bit kOpenBSD @tab ?
5761 @item 64-bit kOpenBSD @tab ?
5762 @item Multiboot @tab ?
5763 @item Multiboot2 @tab ?
5764 @item 32-bit Linux (legacy protocol) @tab no (1)
5765 @item 64-bit Linux (legacy protocol) @tab no (1)
5766 @item 32-bit Linux (modern protocol) @tab ?
5767 @item 64-bit Linux (modern protocol) @tab ?
5768 @item 32-bit XNU @tab ?
5769 @item 64-bit XNU @tab ?
5770 @item 32-bit EFI chainloader @tab no (2)
5771 @item 64-bit EFI chainloader @tab no (2)
5772 @item Appleloader @tab no (2)
5778 @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
5779 @item Some modules may need to be disabled
5783 PowerPC, IA64 and Sparc64 ports support only Linux. MIPS port supports Linux
5788 As 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.
5790 Following variables must be defined:
5792 @multitable @columnfractions .30 .65
5793 @item GRUB_PAYLOADS_DIR @tab directory containing the required kernels
5794 @item GRUB_CBFSTOOL @tab cbfstoll from Coreboot package (for coreboot platform only)
5795 @item GRUB_COREBOOT_ROM @tab empty Coreboot ROM
5796 @item GRUB_QEMU_OPTS @tab additional options to be supplied to QEMU
5801 @multitable @columnfractions .40 .55
5802 @item kfreebsd_env.i386 @tab 32-bit kFreeBSD device hints
5803 @item kfreebsd.i386 @tab 32-bit FreeBSD kernel image
5804 @item kfreebsd.x86_64, kfreebsd_env.x86_64 @tab same from 64-bit kFreeBSD
5805 @item knetbsd.i386 @tab 32-bit NetBSD kernel image
5806 @item knetbsd.miniroot.i386 @tab 32-bit kNetBSD miniroot.kmod.
5807 @item knetbsd.x86_64, knetbsd.miniroot.x86_64 @tab same from 64-bit kNetBSD
5808 @item kopenbsd.i386 @tab 32-bit OpenBSD kernel bsd.rd image
5809 @item kopenbsd.x86_64 @tab same from 64-bit kOpenBSD
5810 @item linux.i386 @tab 32-bit Linux
5811 @item linux.x86_64 @tab 64-bit Linux
5814 @node Troubleshooting
5815 @chapter Error messages produced by GRUB
5818 * GRUB only offers a rescue shell::
5822 @node GRUB only offers a rescue shell
5823 @section GRUB only offers a rescue shell
5825 GRUB's normal start-up procedure involves setting the @samp{prefix}
5826 environment variable to a value set in the core image by
5827 @command{grub-install}, setting the @samp{root} variable to match, loading
5828 the @samp{normal} module from the prefix, and running the @samp{normal}
5829 command (@pxref{normal}). This command is responsible for reading
5830 @file{/boot/grub/grub.cfg}, running the menu, and doing all the useful
5831 things GRUB is supposed to do.
5833 If, instead, you only get a rescue shell, this usually means that GRUB
5834 failed to load the @samp{normal} module for some reason. It may be possible
5835 to work around this temporarily: for instance, if the reason for the failure
5836 is that @samp{prefix} is wrong (perhaps it refers to the wrong device, or
5837 perhaps the path to @file{/boot/grub} was not correctly made relative to the
5838 device), then you can correct this and enter normal mode manually:
5842 # Inspect the current prefix (and other preset variables):
5844 # Find out which devices are available:
5846 # Set to the correct value, which might be something like this:
5847 set prefix=(hd0,1)/grub
5854 However, any problem that leaves you in the rescue shell probably means that
5855 GRUB was not correctly installed. It may be more useful to try to reinstall
5856 it properly using @kbd{grub-install @var{device}} (@pxref{Invoking
5857 grub-install}). When doing this, there are a few things to remember:
5861 Drive ordering in your operating system may not be the same as the boot
5862 drive ordering used by your firmware. Do not assume that your first hard
5863 drive (e.g. @samp{/dev/sda}) is the one that your firmware will boot from.
5864 @file{device.map} (@pxref{Device map}) can be used to override this, but it
5865 is usually better to use UUIDs or file system labels and avoid depending on
5866 drive ordering entirely.
5869 At least on BIOS systems, if you tell @command{grub-install} to install GRUB
5870 to a partition but GRUB has already been installed in the master boot
5871 record, then the GRUB installation in the partition will be ignored.
5874 If possible, it is generally best to avoid installing GRUB to a partition
5875 (unless it is a special partition for the use of GRUB alone, such as the
5876 BIOS Boot Partition used on GPT). Doing this means that GRUB may stop being
5877 able to read its core image due to a file system moving blocks around, such
5878 as while defragmenting, running checks, or even during normal operation.
5879 Installing to the whole disk device is normally more robust.
5882 Check that GRUB actually knows how to read from the device and file system
5883 containing @file{/boot/grub}. It will not be able to read from encrypted
5884 devices with unsupported encryption scheme, nor from file systems for which
5885 support has not yet been added to GRUB.
5889 @node Invoking grub-install
5890 @chapter Invoking grub-install
5892 The program @command{grub-install} generates a GRUB core image using
5893 @command{grub-mkimage} and installs it on your system. You must specify the
5894 device name on which you want to install GRUB, like this:
5897 grub-install @var{install_device}
5900 The device name @var{install_device} is an OS device name or a GRUB
5903 @command{grub-install} accepts the following options:
5907 Print a summary of the command-line options and exit.
5910 Print the version number of GRUB and exit.
5912 @item --boot-directory=@var{dir}
5913 Install GRUB images under the directory @file{@var{dir}/grub/}
5914 This option is useful when you want to install GRUB into a
5915 separate partition or a removable disk.
5916 If this option is not specified then it defaults to @file{/boot}, so
5919 @kbd{grub-install /dev/sda}
5925 @kbd{grub-install --boot-directory=/boot/ /dev/sda}
5928 Here is an example in which you have a separate @dfn{boot} partition which is
5933 @kbd{grub-install --boot-directory=/mnt/boot /dev/sdb}
5937 Recheck the device map, even if @file{/boot/grub/device.map} already
5938 exists. You should use this option whenever you add/remove a disk
5939 into/from your computer.
5943 @node Invoking grub-mkconfig
5944 @chapter Invoking grub-mkconfig
5946 The program @command{grub-mkconfig} generates a configuration file for GRUB
5947 (@pxref{Simple configuration}).
5950 grub-mkconfig -o /boot/grub/grub.cfg
5953 @command{grub-mkconfig} accepts the following options:
5957 Print a summary of the command-line options and exit.
5960 Print the version number of GRUB and exit.
5963 @itemx --output=@var{file}
5964 Send the generated configuration file to @var{file}. The default is to send
5965 it to standard output.
5969 @node Invoking grub-mkpasswd-pbkdf2
5970 @chapter Invoking grub-mkpasswd-pbkdf2
5972 The program @command{grub-mkpasswd-pbkdf2} generates password hashes for
5973 GRUB (@pxref{Security}).
5976 grub-mkpasswd-pbkdf2
5979 @command{grub-mkpasswd-pbkdf2} accepts the following options:
5982 @item -c @var{number}
5983 @itemx --iteration-count=@var{number}
5984 Number of iterations of the underlying pseudo-random function. Defaults to
5987 @item -l @var{number}
5988 @itemx --buflen=@var{number}
5989 Length of the generated hash. Defaults to 64.
5991 @item -s @var{number}
5992 @itemx --salt=@var{number}
5993 Length of the salt. Defaults to 64.
5997 @node Invoking grub-mkrelpath
5998 @chapter Invoking grub-mkrelpath
6000 The program @command{grub-mkrelpath} makes a file system path relative to
6001 the root of its containing file system. For instance, if @file{/usr} is a
6005 $ @kbd{grub-mkrelpath /usr/share/grub/unicode.pf2}
6006 @samp{/share/grub/unicode.pf2}
6009 This is mainly used internally by other GRUB utilities such as
6010 @command{grub-mkconfig} (@pxref{Invoking grub-mkconfig}), but may
6011 occasionally also be useful for debugging.
6013 @command{grub-mkrelpath} accepts the following options:
6017 Print a summary of the command-line options and exit.
6020 Print the version number of GRUB and exit.
6024 @node Invoking grub-mkrescue
6025 @chapter Invoking grub-mkrescue
6027 The program @command{grub-mkrescue} generates a bootable GRUB rescue image
6028 (@pxref{Making a GRUB bootable CD-ROM}).
6031 grub-mkrescue -o grub.iso
6034 All arguments not explicitly listed as @command{grub-mkrescue} options are
6035 passed on directly to @command{xorriso} in @command{mkisofs} emulation mode.
6036 Options passed to @command{xorriso} will normally be interpreted as
6037 @command{mkisofs} options; if the option @samp{--} is used, then anything
6038 after that will be interpreted as native @command{xorriso} options.
6040 Non-option arguments specify additional source directories. This is
6041 commonly used to add extra files to the image:
6044 mkdir -p disk/boot/grub
6045 @r{(add extra files to @file{disk/boot/grub})}
6046 grub-mkrescue -o grub.iso disk
6049 @command{grub-mkrescue} accepts the following options:
6053 Print a summary of the command-line options and exit.
6056 Print the version number of GRUB and exit.
6059 @itemx --output=@var{file}
6060 Save output in @var{file}. This "option" is required.
6062 @item --modules=@var{modules}
6063 Pre-load the named GRUB modules in the image. Multiple entries in
6064 @var{modules} should be separated by whitespace (so you will probably need
6065 to quote this for your shell).
6067 @item --rom-directory=@var{dir}
6068 If generating images for the QEMU or Coreboot platforms, copy the resulting
6069 @file{qemu.img} or @file{coreboot.elf} files respectively to the @var{dir}
6070 directory as well as including them in the image.
6072 @item --xorriso=@var{file}
6073 Use @var{file} as the @command{xorriso} program, rather than the built-in
6076 @item --grub-mkimage=@var{file}
6077 Use @var{file} as the @command{grub-mkimage} program, rather than the
6082 @node Invoking grub-mount
6083 @chapter Invoking grub-mount
6085 The program @command{grub-mount} performs a read-only mount of any file
6086 system or file system image that GRUB understands, using GRUB's file system
6087 drivers via FUSE. (It is only available if FUSE development files were
6088 present when GRUB was built.) This has a number of uses:
6092 It provides a convenient way to check how GRUB will view a file system at
6093 boot time. You can use normal command-line tools to compare that view with
6094 that of your operating system, making it easy to find bugs.
6097 It offers true read-only mounts. Linux does not have these for journalling
6098 file systems, because it will always attempt to replay the journal at mount
6099 time; while you can temporarily mark the block device read-only to avoid
6100 this, that causes the mount to fail. Since GRUB intentionally contains no
6101 code for writing to file systems, it can easily provide a guaranteed
6102 read-only mount mechanism.
6105 It allows you to examine any file system that GRUB understands without
6106 needing to load additional modules into your running kernel, which may be
6107 useful in constrained environments such as installers.
6110 Since it can examine file system images (contained in regular files) just as
6111 easily as file systems on block devices, you can use it to inspect any file
6112 system image that GRUB understands with only enough privileges to use FUSE,
6113 even if nobody has yet written a FUSE module specifically for that file
6117 Using @command{grub-mount} is normally as simple as:
6120 grub-mount /dev/sda1 /mnt
6123 @command{grub-mount} must be given one or more images and a mount point as
6124 non-option arguments (if it is given more than one image, it will treat them
6125 as a RAID set), and also accepts the following options:
6129 Print a summary of the command-line options and exit.
6132 Print the version number of GRUB and exit.
6136 Mount encrypted devices, prompting for a passphrase if necessary.
6138 @item -d @var{string}
6139 @itemx --debug=@var{string}
6140 Show debugging output for conditions matching @var{string}.
6142 @item -K prompt|@var{file}
6143 @itemx --zfs-key=prompt|@var{file}
6144 Load a ZFS encryption key. If you use @samp{prompt} as the argument,
6145 @command{grub-mount} will read a passphrase from the terminal; otherwise, it
6146 will read key material from the specified file.
6148 @item -r @var{device}
6149 @itemx --root=@var{device}
6150 Set the GRUB root device to @var{device}. You do not normally need to set
6151 this; @command{grub-mount} will automatically set the root device to the
6152 root of the supplied file system.
6154 If @var{device} is just a number, then it will be treated as a partition
6155 number within the supplied image. This means that, if you have an image of
6156 an entire disk in @file{disk.img}, then you can use this command to mount
6157 its second partition:
6160 grub-mount -r 2 disk.img mount-point
6165 Print verbose messages.
6169 @node Invoking grub-probe
6170 @chapter Invoking grub-probe
6172 The program @command{grub-probe} probes device information for a given path
6176 grub-probe --target=fs /boot/grub
6177 grub-probe --target=drive --device /dev/sda1
6180 @command{grub-probe} must be given a path or device as a non-option
6181 argument, and also accepts the following options:
6185 Print a summary of the command-line options and exit.
6188 Print the version number of GRUB and exit.
6192 If this option is given, then the non-option argument is a system device
6193 name (such as @samp{/dev/sda1}), and @command{grub-probe} will print
6194 information about that device. If it is not given, then the non-option
6195 argument is a filesystem path (such as @samp{/boot/grub}), and
6196 @command{grub-probe} will print information about the device containing that
6197 part of the filesystem.
6200 @itemx --device-map=@var{file}
6201 Use @var{file} as the device map (@pxref{Device map}) rather than the
6202 default, usually @samp{/boot/grub/device.map}.
6204 @item -t @var{target}
6205 @itemx --target=@var{target}
6206 Print information about the given path or device as defined by @var{target}.
6207 The available targets and their meanings are:
6211 GRUB filesystem module.
6213 Filesystem Universally Unique Identifier (UUID).
6221 GRUB partition map module.
6223 GRUB abstraction module (e.g. @samp{lvm}).
6224 @item cryptodisk_uuid
6226 @item msdos_parttype
6227 MBR partition type code (two hexadecimal digits).
6229 A string of platform search hints suitable for passing to the
6230 @command{search} command (@pxref{search}).
6232 Search hints for the PC BIOS platform.
6233 @item ieee1275_hints
6234 Search hints for the IEEE1275 platform.
6235 @item baremetal_hints
6236 Search hints for platforms where disks are addressed directly rather than
6239 Search hints for the EFI platform.
6241 Search hints for the ARC platform.
6242 @item compatibility_hint
6243 A guess at a reasonable GRUB drive name for this device, which may be
6244 used as a fallback if the @command{search} command fails.
6246 System device name for the whole disk.
6251 Print verbose messages.
6255 @node Invoking grub-script-check
6256 @chapter Invoking grub-script-check
6258 The program @command{grub-script-check} takes a GRUB script file
6259 (@pxref{Shell-like scripting}) and checks it for syntax errors, similar to
6260 commands such as @command{sh -n}. It may take a @var{path} as a non-option
6261 argument; if none is supplied, it will read from standard input.
6264 grub-script-check /boot/grub/grub.cfg
6267 @command{grub-script-check} accepts the following options:
6271 Print a summary of the command-line options and exit.
6274 Print the version number of GRUB and exit.
6278 Print each line of input after reading it.
6282 @node Obtaining and Building GRUB
6283 @appendix How to obtain and build GRUB
6286 @strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
6287 GNU assembler has been changed so that it can produce real 16bits
6288 machine code between 2.9.1 and 2.9.1.0.x. See
6289 @uref{http://sources.redhat.com/binutils/}, to obtain information on
6290 how to get the latest version.
6293 GRUB is available from the GNU alpha archive site
6294 @uref{ftp://ftp.gnu.org/gnu/grub} or any of its mirrors. The file
6295 will be named grub-version.tar.gz. The current version is
6296 @value{VERSION}, so the file you should grab is:
6298 @uref{ftp://ftp.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz}
6300 To unbundle GRUB use the instruction:
6303 @kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -}
6306 which will create a directory called @file{grub-@value{VERSION}} with
6307 all the sources. You can look at the file @file{INSTALL} for detailed
6308 instructions on how to build and install GRUB, but you should be able to
6313 @kbd{cd grub-@value{VERSION}}
6319 Also, the latest version is available using Bazaar. See
6320 @uref{http://www.gnu.org/software/grub/grub-download.html} for more
6323 @node Reporting bugs
6324 @appendix Reporting bugs
6326 These are the guideline for how to report bugs. Take a look at this
6327 list below before you submit bugs:
6331 Before getting unsettled, read this manual through and through. Also,
6332 see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}.
6335 Always mention the information on your GRUB. The version number and the
6336 configuration are quite important. If you build it yourself, write the
6337 options specified to the configure script and your operating system,
6338 including the versions of gcc and binutils.
6341 If you have trouble with the installation, inform us of how you
6342 installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
6343 up when it boots} is not enough.
6345 The information on your hardware is also essential. These are especially
6346 important: the geometries and the partition tables of your hard disk
6347 drives and your BIOS.
6350 If GRUB cannot boot your operating system, write down
6351 @emph{everything} you see on the screen. Don't paraphrase them, like
6352 @samp{The foo OS crashes with GRUB, even though it can boot with the
6353 bar boot loader just fine}. Mention the commands you executed, the
6354 messages printed by them, and information on your operating system
6355 including the version number.
6358 Explain what you wanted to do. It is very useful to know your purpose
6359 and your wish, and how GRUB didn't satisfy you.
6362 If you can investigate the problem yourself, please do. That will give
6363 you and us much more information on the problem. Attaching a patch is
6366 When you attach a patch, make the patch in unified diff format, and
6367 write ChangeLog entries. But, even when you make a patch, don't forget
6368 to explain the problem, so that we can understand what your patch is
6372 Write down anything that you think might be related. Please understand
6373 that we often need to reproduce the same problem you encountered in our
6374 environment. So your information should be sufficient for us to do the
6375 same thing---Don't forget that we cannot see your computer directly. If
6376 you are not sure whether to state a fact or leave it out, state it!
6377 Reporting too many things is much better than omitting something
6381 If you follow the guideline above, submit a report to the
6382 @uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}.
6383 Alternatively, you can submit a report via electronic mail to
6384 @email{bug-grub@@gnu.org}, but we strongly recommend that you use the
6385 Bug Tracking System, because e-mail can be passed over easily.
6387 Once we get your report, we will try to fix the bugs.
6391 @appendix Where GRUB will go
6393 GRUB 2 is now quite stable and used in many production systems. We are
6394 currently working towards a 2.0 release.
6396 If you are interested in the development of GRUB 2, take a look at
6397 @uref{http://www.gnu.org/software/grub/grub.html, the homepage}.
6403 @node Copying This Manual
6404 @appendix Copying This Manual
6407 * GNU Free Documentation License:: License for copying this manual.
6416 @c Currently, we use only the Concept Index.
6424 This is an attempt to make a manual for GRUB 2. The contents are
6425 copied from the GRUB manual in GRUB Legacy, so they are not always
6426 appropriate yet for GRUB 2.