Grub Manual

7/30/2019 Grub Manual

1/106


2/106


3/106

i

Table o Contents

1 Introduction to GRUB . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 History o GRUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Diferences rom previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 GRUB eatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.5 The role o a boot loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Naming convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.1 Installing GRUB using grub-install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Making a GRUB bootable CD-ROM. . . . . . . . . . . . . . . . . . . . . . . . . .

103.3 The map between BIOS drives and OS devices . . . . . . . . . . . . . . . . 103.4 BIOS installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 Booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.1 How to boot operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.1.1 How to boot an OS directly with GRUB . . . . . . . . . . . . . . . . . . 134.1.2 Chain-loading an OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.2 Some caveats on OS-specic issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2.1 GNU/Hurd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.2.2 GNU/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.2.3 DOS/Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15

5 Writing your own conguration le . . . . . . . . . . 175.1 Simple conguration handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Writing ull conguration les directly . . . . . . . . . . . . . . . . . . . . . . . . . 205.3 Embedding a conguration le into GRUB . . . . . . . . . . . . . . . . . . . . 23

6 Theme le ormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.2 Theme Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.2.1 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.2.2 Fonts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

256.2.3 Progress Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.2.4 Circular Progress Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.2.5 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.2.6 Boot Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.2.7 Styled Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266.2.8 Creating Styled Box Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.3 Theme File Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27


4/106

ii GNU GRUB Manual 1.99

6.3.1 Global Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.3.2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.3.3 Global Property List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.3.4 Component Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.3.5 Component List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.3.6 Common properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

7 Booting GRUB rom the network . . . . . . . . . . . . 33

8 Using GRUB via a serial line . . . . . . . . . . . . . . . . . 35

9 Using GRUB with vendor power-on keys . . . 37

10 GRUB image les . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

11 Filesystem syntax and semantics. . . . . . . . . . . .

4111.1 How to speciy devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4111.2 How to speciy les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4111.3 How to speciy block lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

12 GRUBs user interace . . . . . . . . . . . . . . . . . . . . . . . 4312.1 The exible command-line interace . . . . . . . . . . . . . . . . . . . . . . . . . . 4312.2 The simple menu interace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4412.3 Editing a menu entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

13 GRUB environment variables . . . . . . . . . . . . . . . 45

13.1 Special environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4513.1.1 biosnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.1.2 chosen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.1.3 color highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.1.4 color normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.1.5 debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4613.1.6 deault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4613.1.7 allback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4613.1.8 gxmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713.1.9 gxpayload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713.1.10 gxterm ont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713.1.11 icondir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713.1.12 lang

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

13.1.13 locale dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4713.1.14 menu color highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.15 menu color normal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.16 net pxe boot le. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.17 net pxe dhcp server name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.18 net pxe domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.19 net pxe extensionspath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48


5/106

iii

13.1.20 net pxe hostname. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.21 net pxe ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.22 net pxe mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.23 net pxe rootpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.24 pager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4813.1.25 prex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.26 pxe blksize

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4913.1.27 pxe deault gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.28 pxe deault server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.29 root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.30 superusers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.31 theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4913.1.32 timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

13.2 The GRUB environment block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

14 The list o available commands . . . . . . . . . . . . . 5114.1 The list o commands or the menu only. . . . . . . . . . . . . . . . . . . . . . 51

14.1.1 menuentry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5114.1.2 submenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

14.2 The list o general commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5214.2.1 serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5214.2.2 terminal input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5214.2.3 terminal output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5214.2.4 termino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

14.3 The list o command-line and menu entry commands . . . . . . . . . 5314.3.1 acpi. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5314.3.2 badram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5314.3.3 blocklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

14.3.4 boot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5414.3.5 cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5414.3.6 chainloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5414.3.7 cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5414.3.8 congle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5414.3.9 cpuid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5514.3.10 crc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5514.3.11 date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5514.3.12 drivemap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5514.3.13 echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5514.3.14 export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5614.3.15 alse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

14.3.16 gettext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5614.3.17 gptsync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5614.3.18 halt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5614.3.19 help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5714.3.20 initrd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5714.3.21 initrd16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5714.3.22 insmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5714.3.23 keystatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57


6/106


7/106


8/106


9/106


10/106

2 GNU GRUB Manual 1.99

Yoshinori K. Okuji adopted GRUB as an ocial GNU package, and opened its developmentby making the latest sources available via anonymous CVS. See Appendix A [Obtaining andBuilding GRUB], page 83, or more inormation.

Over the next ew years, GRUB was extended to meet many needs, but it quicklybecame clear that its design was not keeping up with the extensions being made to it, and wereached the point where it was very dicult to make any urther changes without breakingexisting eatures. Around 2002, Yoshinori K. Okuji started work on PUPA (PreliminaryUniversal Programming Architecture or GNU GRUB), aiming to rewrite the core o GRUBto make it cleaner, saer, more robust, and more powerul. PUPA was eventually renamed toGRUB 2, and the original version o GRUB was renamed to GRUB Legacy. Small amountso maintenance continued to be done on GRUB Legacy, but the last release (0.97) was madein 2005 and at the time o writing it seems unlikely that there will be another.

By around 2007, GNU/Linux distributions started to use GRUB 2 to limited extents,and by the end o 2009 multiple major distributions were installing it by deault.

1.3 Diferences rom previous versionsGRUB 2 is a rewrite o GRUB (see Section 1.2 [History], page 1), although it shares manycharacteristics with the previous version, now known as GRUB Legacy. Users o GRUBLegacy may need some guidance to nd their way around this new version.

The conguration le has a new name (grub.cfg rather than menu.lst orgrub.conf), new syntax (see Chapter 5 [Conguration], page 17) and many newcommands (see Chapter 14 [Commands], page 51). Conguration cannot be copiedover directly, although most GRUB Legacy users should not nd the syntax toosurprising.

grub.cfg is typically automatically generated by grub-mkconfig (see Section 5.1[Simple conguration], page 17). This makes it easier to handle versioned kernel up-grades.

Partition numbers in GRUB device names now start at 1, not 0 (see Chapter 2 [Namingconvention], page 7).

The conguration le is now written in something closer to a ull scripting language:variables, conditionals, and loops are available.

A small amount o persistent storage is available across reboots, using the save_envand load_env commands in GRUB and the grub-editenv utility. This is not availablein all congurations (see Section 13.2 [Environment block], page 49).

GRUB 2 has more reliable ways to nd its own les and those o target kernels onmultiple-disk systems, and has commands (see Section 14.3.40 [search], page 61) to

nd devices using le system labels or Universally Unique Identiers (UUIDs). GRUB 2 is available or several other types o system in addition to the PC BIOS

systems supported by GRUB Legacy: PC EFI, PC coreboot, PowerPC, SPARC, andMIPS Lemote Yeeloong are all supported.

Many more le systems are supported, including but not limited to ext4, HFS +, andNTFS.

GRUB 2 can read les directly rom LVM and RAID devices.

A graphical terminal and a graphical menu system are available.


11/106

Chapter 1: Introduction to GRUB 3

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

The image les (see Chapter 10 [Images], page 39) that make up GRUB have beenreorganised; Stage 1, Stage 1.5, and Stage 2 are no more.

GRUB 2 puts many acilities in dynamically loaded modules, allowing the core imageto be smaller, and allowing the core image to be built in more exible ways.

1.4 GRUB eatures

The primary requirement or GRUB is that it be compliant with the Multiboot Specifcation,which is described in Section Motivation in The Multiboot Specifcation.

The other goals, listed in approximate order o importance, are:

Basic unctions must be straightorward or end-users.

Rich unctionality to support kernel experts and designers.

Backward compatibility or booting FreeBSD, NetBSD, OpenBSD, and Linux. Propri-etary kernels (such as DOS, Windows NT, and OS/2) are supported via a chain-loadingunction.

Except or specic compatibility modes (chain-loading and the Linux piggyback or-mat), all kernels will be started in much the same state as in the Multiboot Specication.Only kernels loaded at 1 megabyte or above are presently supported. Any attempt to loadbelow that boundary will simply result in immediate ailure and an error message reportingthe problem.

In addition to the requirements above, GRUB has the ollowing eatures (note thatthe Multiboot Specication doesnt require all the eatures that GRUB supports):

Recognize multiple executable ormatsSupport many o the a.out variants plus ELF. Symbol tables are also loaded.

Support non-Multiboot kernelsSupport many o the various ree 32-bit kernels that lack Multiboot compliance(primarily FreeBSD, NetBSD, OpenBSD, and Linux). Chain-loading o otherboot loaders is also supported.

Load multiples modulesFully support the Multiboot eature o loading multiple modules.

Load a conguration leSupport a human-readable text conguration le with preset boot commands.

You can also load another conguration le dynamically and embed a presetconguration le in a GRUB image le. The list o commands (see Chapter 14[Commands], page 51) are a superset o those supported on the command-line.An example conguration le is provided in Chapter 5 [Conguration], page 17.

Provide a menu interaceA menu interace listing preset boot commands, with a programmable timeout,is available. There is no xed limit on the number o boot entries, and thecurrent implementation has space or several hundred.
http://multiboot.pdf/http://multiboot.pdf/http://multiboot.pdf/


12/106


Have a exible command-line interaceA airly exible command-line interace, accessible rom the menu, is availableto edit any preset commands, or write a new boot command set rom scratch.I no conguration le is present, GRUB drops to the command-line.

The list o commands (see Chapter 14 [Commands], page 51) are a subset othose supported or conguration les. Editing commands closely resembles theBash command-line (see Section Command Line Editing in Bash Features),with TAB-completion o commands, devices, partitions, and les in a directorydepending on context.

Support multiple lesystem typesSupport multiple lesystem types transparently, plus a useul explicitblocklist notation. The currently supported lesystem types are Amiga FastFileSystem (AFFS), AtheOS s, BeFS, cpio, Linux ext2/ext3/ext4, DOSFAT12/FAT16/FAT32, HFS, HFS+, ISO9660, JFS, Minix s, nils2, NTFS,

ReiserFS, Amiga Smart FileSystem (SFS), tar, UDF, BSD UFS/UFS2, andXFS. See Chapter 11 [Filesystem], page 41, or more inormation.

Support automatic decompressionCan decompress les which were compressed by gzip or xz2. This unction isboth automatic and transparent to the user (i.e. all unctions operate upon theuncompressed contents o the specied les). This greatly reduces a le sizeand loading time, a particularly great benet or oppies.3

It is conceivable that some kernel modules should be loaded in a compressedstate, so a diferent module-loading command can be specied to avoid uncom-pressing the modules.

Access data on any installed deviceSupport reading data rom any or all oppies or hard disk(s) recognized by theBIOS, independent o the setting o the root device.

Be independent o drive geometry translationsUnlike many other boot loaders, GRUB makes the particular drive translationirrelevant. A drive installed and running with one translation may be convertedto another translation without any adverse efects or changes in GRUBs con-guration.

Detect all installed ramGRUB can generally nd all the installed ram on a PC-compatible machine. It

uses an advanced BIOS query technique or nding all memory regions. As de-scribed on the Multiboot Specication (see Section Motivation in The Multi-boot Specifcation), not all kernels make use o this inormation, but GRUBprovides it or those who do.

2 Only CRC32 data integrity check is supported (xz deault is CRC64 so one should use check=crc32option). LZMA BCJ flters are supported.

3 There are a ew pathological cases where loading a very badly organized ELF kernel might takelonger, but in practice this never happen.
http://features.pdf/http://features.pdf/http://multiboot.pdf/http://multiboot.pdf/http://multiboot.pdf/http://multiboot.pdf/http://multiboot.pdf/http://features.pdf/


13/106

Chapter 1: Introduction to GRUB 5

Support Logical Block Address modeIn traditional disk calls (called CHS mode), there is a geometry translationproblem, that is, the BIOS cannot access over 1024 cylinders, so the accessiblespace is limited to at least 508 MB and to at most 8GB. GRUB cant univer-sally solve this problem, as there is no standard interace used in all machines.However, several newer machines have the new interace, Logical Block Address(LBA) mode. GRUB automatically detects i LBA mode is available and usesit i available. In LBA mode, GRUB can access the entire disk.

Support network bootingGRUB is basically a disk-based boot loader but also has network support. Youcan load OS images rom a network by using the TFTP protocol.

Support remote terminalsTo support computers with no console, GRUB provides remote terminal sup-port, so that you can control GRUB rom a remote host. Only serial terminal

support is implemented at the moment.

1.5 The role o a boot loader

The ollowing is a quotation rom Gordon Matzigkeit, a GRUB anatic:

Some people like to acknowledge both the operating system and kernel whenthey talk about their computers, so they might say they use GNU/Linuxor GNU/Hurd. Other people seem to think that the kernel is the mostimportant part o the system, so they like to call their GNU operating systemsLinux systems.

I, personally, believe that this is a grave injustice, because the boot loader is themost important sotware o all. I used to reer to the above systems as either

LILO4

or GRUB systems.Unortunately, nobody ever understood what I was talking about; now I justuse the word GNU as a pseudonym or GRUB.

So, i you ever hear people talking about their alleged GNU systems, remem-ber that they are actually paying homage to the best boot loader around. . .GRUB!

We, the GRUB maintainers, do not (usually) encourage Gordons level o anaticism,but it helps to remember that boot loaders deserve recognition. We hope that you enjoyusing GNU GRUB as much as we did writing it.

4 The LInux LOader, a boot loader that everybody uses, but nobody likes.


14/106


15/106


16/106


17/106


18/106


This install doesnt conict with standard install as long as they are in separatedirectories.

Note that grub-install is actually just a shell script and the real task is done bygrub-mkimage and grub-setup. Thereore, you may run those commands directly to installGRUB, without using grub-install. Dont do that, however, unless you are very amiliarwith the internals o GRUB. Installing a boot loader on a running OS may be extremelydangerous.

3.2 Making a GRUB bootable CD-ROM

GRUB supports the no emulation mode in the El Torito specication1. This means thatyou can use the whole CD-ROM rom GRUB and you dont have to make a oppy or harddisk image le, which can cause compatibility problems.

For booting rom a CD-ROM, GRUB uses a special image called cdboot.img, whichis concatenated with core.img. The core.img used or this should be built with at leastthe iso9660 and biosdisk modules. Your bootable CD-ROM will usually also need toinclude a conguration le grub.cfg and some other GRUB modules.

To make a simple generic GRUB rescue CD, you can use the grub-mkrescue program(see Chapter 22 [Invoking grub-mkrescue], page 81):

$ grub-mkrescue -o grub.iso

You will oten need to include other les in your image. To do this, rst make a topdirectory or the bootable image, say, iso:

$ mkdir iso

Make a directory or GRUB:

$ mkdir -p iso/boot/grub

I desired, make the cong le grub.cfg under iso/boot/grub (see Chapter 5

[Conguration], page 17), and copy any les and directories or the disc to the directoryiso/.

Finally, make the image:

$ grub-mkrescue -o grub.iso iso

This produces a le named grub.iso, which then can be burned into a CD (or aDVD), or written to a USB mass storage device.

The root device will be set up appropriately on entering your grub.cfg congura-tion le, so you can reer to le names on the CD without needing to use an explicit devicename. This makes it easier to produce rescue images that will work on both optical drivesand USB mass storage devices.

3.3 The map between BIOS drives and OS devicesThe grub-mkdevicemap program can be used to create the device map fle. It is oten runautomatically by tools such as grub-install i the device map le does not already exist.The le name /boot/grub/device.map is preerred.

I the device map le exists, the GRUB utilities (grub-probe, grub-setup, etc.)read it to map BIOS drives to OS devices. This le consists o lines like this:

1 El Torito is a specifcation or bootable CD using BIOS unctions.


19/106


20/106


21/106

Chapter 4: Booting 13

4 Booting

GRUB can load Multiboot-compliant kernels in a consistent way, but or some ree operating

systems you need to use some OS-specic magic.

4.1 How to boot operating systems

GRUB has two distinct boot methods. One o the two is to load an operating system directly,and the other is to chain-load another boot loader which then will load an operating systemactually. Generally speaking, the ormer is more desirable, because you dont need to installor maintain other boot loaders and GRUB is exible enough to load an operating systemrom an arbitrary disk/partition. However, the latter is sometimes required, since GRUBdoesnt support all the existing operating systems natively.

4.1.1 How to boot an OS directly with GRUB

Multiboot (see Section Motivation in The Multiboot Specifcation) is the native ormatsupported by GRUB. For the sake o convenience, there is also support or Linux, FreeBSD,NetBSD and OpenBSD. I you want to boot other operating systems, you will have tochain-load them (see Section 4.1.2 [Chain-loading], page 13).

FIXME: this section is incomplete.

1. Run the command boot (see Section 14.3.4 [boot], page 54).

However, DOS and Windows have some deciencies, so you might have to use morecomplicated instructions. See Section 4.2.3 [DOS/Windows], page 15, or more inormation.

4.1.2 Chain-loading an OS

Operating systems that do not support Multiboot and do not have specic support inGRUB (specic support is available or Linux, FreeBSD, NetBSD and OpenBSD) must bechain-loaded, which involves loading another boot loader and jumping to it in real mode.

The chainloader command (see Section 14.3.6 [chainloader], page 54) is used to setthis up. It is normally also necessary to load some GRUB modules and set the appropriateroot device. Putting this together, we get something like this, or a Windows system on therst partition o the rst hard disk:

menuentry "Windows" {

insmod chain

insmod ntfs

set root=(hd0,1)

chainloader +1

}

On systems with multiple hard disks, an additional workaround may be required.See Section 4.2.3 [DOS/Windows], page 15.

Chain-loading is only supported on PC BIOS and EFI platorms.

4.2 Some caveats on OS-specic issues

Here, we describe some caveats on several operating systems.
http://multiboot.pdf/http://multiboot.pdf/http://multiboot.pdf/


22/106


4.2.1 GNU/Hurd

Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is nothing special aboutit. But do not orget that you have to speciy a root partition to the kernel.

1. Set GRUBs root device to the same drive as GNU/Hurds. The command search --file --set /boot/gnumach.gz or similar may help you (see Section 14.3.40 [search],page 61).

2. Load the kernel and the modules, like this:

grub> multiboot /boot/gnumach.gz root=device:hd0s1

grub> module /hurd/ext2fs.static ext2fs --readonly \

--multiboot-command-line=${kernel-command-line} \--host-priv-port=${host-port} \--device-master-port=${device-port} \--exec-server-task=${exec-task} -T typed ${root} \$(task-create) $(task-resume)

grub> module /lib/ld.so.1 exec /hurd/exec $(exec-task=task-create)3. Finally, run the command boot (see Section 14.3.4 [boot], page 54).

4.2.2 GNU/Linux

It is relatively easy to boot GNU/Linux rom GRUB, because it somewhat resembles toboot a Multiboot-compliant OS.

1. Set GRUBs root device to the same drive as GNU/Linuxs. The command search--file --set /vmlinuz or similar may help you (see Section 14.3.40 [search], page 61).

2. Load the kernel using the command linux (see Section 14.3.24 [linux], page 57):

grub> linux /vmlinuz root=/dev/sda1

I you need to speciy some kernel parameters, just append them to the command. Forexample, to set acpi to off, do this:

grub> linux /vmlinuz root=/dev/sda1 acpi=off

See the documentation in the Linux source tree or complete inormation on the avail-able options.

With linux GRUB uses 32-bit protocol. Some BIOS services like APM or EDD arentavailable with this protocol. In this case you need to use linux16

grub> linux16 /vmlinuz root=/dev/sda1 acpi=off

3. I you use an initrd, execute the command initrd (see Section 14.3.20 [initrd], page 57)ater linux:

grub> initrd /initrd

I you used linux16 you need to use initrd16:

grub> initrd16 /initrd

4. Finally, run the command boot (see Section 14.3.4 [boot], page 54).

Caution: I you use an initrd and speciy the mem= option to the kernel to let it useless than actual memory size, you will also have to speciy the same memory size to GRUB.To let GRUB know the size, run the command uppermem before loading the kernel. SeeSection 14.3.45 [uppermem], page 64, or more inormation.


23/106

Chapter 4: Booting 15

4.2.3 DOS/Windows

GRUB cannot boot DOS or Windows directly, so you must chain-load them (seeSection 4.1.2 [Chain-loading], page 13). However, their boot loaders have some critical

deciencies, so it may not work to just chain-load them. To overcome the problems,GRUB provides you with two helper unctions.

I you have installed DOS (or Windows) on a non-rst hard disk, you have to usethe disk swapping technique, because that OS cannot boot rom any disks but the rst one.The workaround used in GRUB is the command drivemap (see Section 14.3.12 [drivemap],page 55), like this:

drivemap -s (hd0) (hd1)

This perorms a virtual swap between your rst and second hard drive.

Caution: This is efective only i DOS (or Windows) uses BIOS to access the swappeddisks. I that OS uses a special driver or the disks, this probably wont work.

Another problem arises i you installed more than one set o DOS/Windows onto

one disk, because they could be conused i there are more than one primary partitions orDOS/Windows. Certainly you should avoid doing this, but there is a solution i you dowant to do so. Use the partition hiding/unhiding technique.

I GRUB hides a DOS (or Windows) partition (see Section 14.3.32 [parttool],page 59), DOS (or Windows) will ignore the partition. I GRUB unhides a DOS (orWindows) partition, DOS (or Windows) will detect the partition. Thus, i you haveinstalled DOS (or Windows) on the rst and the second partition o the rst hard disk,and you want to boot the copy on the rst partition, do the ollowing:

parttool (hd0,1) hidden-

parttool (hd0,2) hidden+

set root=(hd0,1)

chainloader +1parttool ${root} boot+

boot


24/106


25/106

Chapter 5: Writing your own conguration le 17

5 Writing your own conguration le

GRUB is congured using grub.cfg, usually located under /boot/grub. This le is quite

exible, but most users will not need to write the whole thing by hand.

5.1 Simple conguration handling

The program grub-mkconfig (see Chapter 20 [Invoking grub-mkcong], page 77) generatesgrub.cfg les suitable or most cases. It is suitable or use when upgrading a distribution,and will discover available kernels and attempt to generate menu entries or them.

grub-mkconfig does have some limitations. While adding extra custom menu en-tries to the end o the list can be done by editing /etc/grub.d/40_custom or creat-ing /boot/grub/custom.cfg, changing the order o menu entries or changing their titlesmay require making complex changes to shell scripts stored in /etc/grub.d/. This maybe improved in the uture. In the meantime, those who eel that it would be easier to

write grub.cfg directly are encouraged to do so (see Chapter 4 [Booting], page 13, andSection 5.2 [Shell-like scripting], page 20), and to disable any system provided by theirdistribution to automatically run grub-mkconfig.

The le /etc/default/grub controls the operation ogrub-mkconfig. It is sourcedby a shell script, and so must be valid POSIX shell input; normally, it will just be a sequenceo KEY=value lines, but i the value contains spaces or other special characters then it mustbe quoted. For example:

GRUB_TERMINAL_INPUT="console serial"

Valid keys in /etc/default/grub are as ollows:

GRUB_DEFAULT

The deault menu entry. This may be a number, in which case it identiesthe Nth entry in the generated menu counted rom zero, or the title o a menuentry, or the special string saved. Using the title may be useul i you wantto set a menu entry as the deault even though there may be a variable numbero entries beore it.

For example, i you have:

menuentry Example GNU/Linux distribution --class gnu-linux {

...

}

then you can make this the deault using:

GRUB_DEFAULT=Example GNU/Linux distribution

I you set this to saved, then the deault menu entry will be that saved byGRUB_SAVEDEFAULT, grub-set-default, or grub-reboot.

The deault is 0.

GRUB_SAVEDEFAULTI this option is set to true, then, when an entry is selected, save it asa new deault entry or use by uture runs o GRUB. This is only useul iGRUB_DEFAULT=saved; it is a separate option because GRUB_DEFAULT=saved


26/106


is useul without this option, in conjunction with grub-set-default or grub-reboot. Unset by deault. This option relies on the environment block, whichmay not be available in all situations (see Section 13.2 [Environment block],page 49).

GRUB_TIMEOUTBoot the deault entry this many seconds ater the menu is displayed, unlessa key is pressed. The deault is 5. Set to 0 to boot immediately withoutdisplaying the menu, or to -1 to wait indenitely.

GRUB_HIDDEN_TIMEOUTWait this many seconds or a key to be pressed beore displaying the menu. Ino key is pressed during that time, boot immediately. Unset by deault.

GRUB_HIDDEN_TIMEOUT_QUIETIn conjunction with GRUB_HIDDEN_TIMEOUT, set this to true to suppress theverbose countdown while waiting or a key to be pressed beore displaying themenu. Unset by deault.

GRUB_DEFAULT_BUTTONGRUB_TIMEOUT_BUTTONGRUB_HIDDEN_TIMEOUT_BUTTONGRUB_BUTTON_CMOS_ADDRESS

Variants o the corresponding variables without the _BUTTON sux, used tosupport vendor-specic power buttons. See Chapter 9 [Vendor power-on keys],page 37.

GRUB_DISTRIBUTORSet by distributors o GRUB to their identiying name. This is used to generate

more inormative menu entry titles.

GRUB_TERMINAL_INPUTSelect the terminal input device. You may select multiple devices here, sepa-rated by spaces.

Valid terminal input names depend on the platorm, but may include console(PC BIOS and EFI consoles), serial (serial terminal), ofconsole (OpenFirmware console), at_keyboard (PC AT keyboard, mainly useul with Core-boot), or usb_keyboard (USB keyboard using the HID Boot Protocol, orcases where the rmware does not handle this).

The deault is to use the platorms native terminal input.

GRUB_TERMINAL_OUTPUTSelect the terminal output device. You may select multiple devices here, sepa-rated by spaces.

Valid terminal output names depend on the platorm, but may includeconsole (PC BIOS and EFI consoles), serial (serial terminal), gfxterm(graphics-mode output), ofconsole (Open Firmware console), or vga_text(VGA text output, mainly useul with Coreboot).

The deault is to use the platorms native terminal output.


27/106


28/106


29/106


30/106


31/106


32/106


33/106

Chapter 6: Theme le ormat 25

6 Theme le ormat

6.1 Introduction

The GRUB graphical menu supports themes that can customize the layout and appearanceo the GRUB boot menu. The theme is congured through a plain text le that speciesthe layout o the various GUI components (including the boot menu, timeout progress bar,and text messages) as well as the appearance using colors, onts, and images. Example isavailable in docs/example theme.txt

6.2 Theme Elements

6.2.1 Colors

Colors can be specied in several ways:

HTML-style #RRGGBB or #RGB ormat, where *R*, *G*, and *B* are hex-adecimal digits (e.g., #8899FF)

as comma-separated decimal RGB values (e.g., 128, 128, 255)

with SVG 1.0 color names (e.g., cornowerblue) which must be specied in lower-case.

6.2.2 Fonts

The onts GRUB uses PFF2 ont ormat bitmap onts. Fonts are specied with ull ontnames. Currently there is no provision or a preerence list o onts, or deriving one ontrom another. Fonts are loaded with the loadont command in GRUB. To see the list oloaded onts, execute the lsonts command. I there are too many onts to t on screen,

do set pager=1 beore executing lsonts.

6.2.3 Progress Bar

Figure 6.1

Figure 6.2

Progress bars are used to display the remaining time beore GRUB boots the deaultmenu entry. To create a progress bar that will display the remaining time beore automaticboot, simply create a progress bar component with the id timeout . This indicatesto GRUB that the progress bar should be updated as time passes, and it should be madeinvisible i the countdown to automatic boot is interrupted by the user.

Progress bars may optionally have text displayed on them. This is controlled throughthe show text property, which can be set to either true or alse to control whethertext is displayed. When GRUB is counting down to automatic boot, the text inorms theuser o the number o seconds remaining.

6.2.4 Circular Progress Indicator

The circular progress indicator unctions similarly to the progress bar. When given an id o timeout , GRUB updates the circular progress indicators value to indicate the time


34/106


35/106


2. Create a new layer on the top o the layer stack. Make it visible. Select this layer asthe current layer.

3. Draw 9 rectangles on your drawing where youd like the slices to be. Clear the ll

option, and set the stroke to 1 pixel wide solid stroke. The corners o the slices mustmeet precisely; i it is of by a single pixel, it will probably be evident when the styledbox is rendered in the GRUB menu. You should probably go to File | DocumentProperties | Grids and enable a grid or create a guide (click on one o the rulers nextto the drawing and drag over the drawing; release the mouse button to place the guide)to help place the rectangles precisely.

4. Right click on the center slice rectangle and choose Object Properties. Change the"Id" to slice c and click Set. Repeat this or the remaining 8 rectangles, giving themId values o slice n, slice ne, slice e, and so on according to the location.

5. Save the drawing.

6. 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.7. Click the layer hide icon or the slice layer in the layer palette. The rectangles will

remain selected, even though they are hidden.

8. 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 willcreate PNG les in the same directory as the drawing, named ater the slices. Thesecan now be used or a styled box in a GRUB theme.

6.3 Theme File Manual

The theme le is a plain text le. Lines that begin with # are ignored and consideredcomments. (Note: This may not be the case i the previous line ended where a value wasexpected.)

The theme le contains two types o statements:

1. Global properties.

2. Component construction.

6.3.1 Global Properties

6.3.2 Format

Global properties are specied with the simple ormat:

name1: value1

name2: "value which may contain spaces"

name3: #88F

In this example, name3 is assigned a color value.

6.3.3 Global Property List

title-text Species the text to display at the top center o thescreen as a title.


36/106


title-ont Denes the ont used or the title message at the topo the screen.

title-color Denes the color o the title message.message-ont Denes the ont used or messages, such as when

GRUB is unable to automatically boot an entry.

message-color Denes the color o the message text.message-bg-color Denes the background color o the message text

area.

desktop-image Species the image to use as the background. It willbe scaled to t the screen size.

desktop-color Species the color or the background i *desktop-image* is not specied.

terminal-box Species the le name pattern or the styled boxslices used or the command line terminal window.For example, terminal-box: terminal *.png will

use the images terminal c.png as the center area,terminal n.png as the north (top) edge, termi-nal nw.png as the northwest (upper let) corner,and so on. I the image or any slice is not ound, itwill simply be let empty.

6.3.4 Component Construction

Greater customizability comes is provided by components. A tree o components orms theuser interace. *Containers* are components that can contain other components, and thereis always a single root component which is an instance o a *canvas* container.

Components are created in the theme le by prexing the type o component with a

+ sign:

+ label { text="GRUB" font="aqui 11" color="#8FF" }

properties o a component are specied as "name = value" (whitespace surroundingtokens is optional and is ignored) where *value* may be:

a single word (e.g., align = center, color = #FF8080),

a quoted string (e.g., text = "Hello, World!"), or

a tuple (e.g., preerred size = (120, 80)).

6.3.5 Component List

The ollowing is a list o the components and the properties they support.

label A label displays a line o text.

Properties:

text The text to display.ont The ont to use or text display.color The color o the text.align The horizontal alignment o the text within the component.

Options are let, center, and right.


37/106


image A component that displays an image. The image is scaled to t the compo-nent, although the preerred size deaults to the images original size unless the pre-erred size property is explicitly set.

Properties:le The ull path to the image le to load.

progress bar Displays a horizontally oriented progress bar. It can be rendered usingsimple solid lled rectangles, or using a pair o pixmap styled boxes.

Properties:

g color The oreground color or plain solid color rendering.bg color The background color or plain solid color rendering.border color The border color or plain solid color rendering.text color The text color.show text Boolean value indicating whether or not text should be dis-

played on the progress bar. I set to *alse*, then no text will

be displayed on the bar. I set to any other value, text willbe displayed on the bar.

bar style The styled box specication or the rame o the progress bar.Example: progress rame *.png

highlight style The styled box specication or the highlighted region o theprogress bar. This box will be used to paint just the high-lighted region o the bar, and will be increased in size as thebar nears completion. Example: progress hl *.png.

text The text to display on the progress bar. I the progress barsID is set to timeout , then GRUB will updated this prop-erty with an inormative message as the timeout approaches.

value The progress bar current value. Normally not set manually.start The progress bar start value. Normally not set manually.end The progress bar end value. Normally not set manually.

circular progress Displays a circular progress indicator. The appearance o this compo-nent is determined by two images: the *center* image and the *tick* image. The centerimage is generally larger and will be drawn in the center o the component. Around thecircumerence o a circle within the component, the tick image will be drawn a certainnumber o times, depending on the properties o the component.

Properties:

center bitmap The le name o the image to draw in the center o the component.

tick bitmap The le name o the image to draw or the tickmarks.

num ticks The number o ticks that make up a ull circle.ticks disappear Boolean value indicating whether tick marks should

progressively appear, or progressively disappear as*value* approaches *end*. Speciy true or alse.

value The progress indicator current value. Normally notset manually.


38/106


start The progress indicator start value. Normally not setmanually.

end The progress indicator end value. Normally not setmanually.

boot menu Displays the GRUB boot menu. It allows selecting items and executingthem.

Properties:

item ont The ont to use or the menu item titles.selected item ont The ont to use or the selected menu item,

or inherit (the deault) to use item ontor the selected menu item as well.

item color The color to use or the menu item titles.selected item color The color to use or the selected menu

item, or inherit (the deault) to use

item color or the selected menu item aswell.

icon width The width o menu item icons. Icons arescaled to the specied size.

icon height The height o menu item icons.item height The height o each menu item in pixels.item padding The amount o space in pixels to leave on

each side o the menu item contents.

item icon space The space between an items icon and thetitle text, in pixels.

item spacing The amount o space to leave between menu

items, in pixels.menu pixmap style The image le pattern or the menu ramestyled box. Example: menu *.png (thiswill use images such as menu c.png,menu w.png, menu nw.png, etc.)

selected item pixmap style The image le pattern or the selected itemhighlight styled box.

scrollbar Boolean value indicating whether the scrollbar should be drawn i the rame and thumbstyled boxes are congured.

scrollbar rame The image le pattern or the entire scrollbar. Example: scrollbar *.png

scrollbar thumb The image le pattern or the scroll barthumb (the part o the scroll bar that movesas scrolling occurs). Example: scroll-bar thumb *.png

max items shown The maximum number o items to showon the menu. I there are more than*max items shown* items in the menu, thelist will scroll to make all items accessible.


39/106


40/106


41/106

Chapter 7: Booting GRUB rom the network 33

7 Booting GRUB rom the network

The ollowing instructions only work on PC BIOS systems where the Preboot eXecutionEnvironment (PXE) is available.

To generate a PXE boot image, run:

grub-mkimage --format=i386-pc-pxe --output=grub.pxe --prefix=(pxe)/boot/grub p

Copy grub.pxe, /boot/grub/*.mod, and /boot/grub/*.lst to the PXE(TFTP) server, ensuring that *.mod and *.lst are accessible via the /boot/grub/path rom the TFTP server root. Set the DHCP server conguration to ofer grub.pxeas the boot le (the filename option in ISC dhcpd).

You can also use the grub-mknetdir utility to generate an image and a GRUBdirectory tree, rather than copying les around manually.

Ater GRUB has started, les on the TFTP server will be accessible via the (pxe)device.

The server and gateway IP address can be controlled by changing the (pxe) devicename to (pxe:server-ip ) or (pxe:server-ip :gateway-ip ). Note that this should bechanged both in the prex and in any reerences to the device name in the congurationle.

GRUB provides several environment variables which may be used to inspect orchange the behaviour o the PXE device:

net_pxe_ipThe IP address o this machine. Read-only.

net_pxe_macThe network interaces MAC address. Read-only.

net_pxe_hostnameThe client host name provided by DHCP. Read-only.

net_pxe_domainThe client domain name provided by DHCP. Read-only.

net_pxe_rootpathThe path to the clients root disk provided by DHCP. Read-only.

net_pxe_extensionspathThe path to additional DHCP vendor extensions provided by DHCP. Read-only.

net_pxe_boot_fileThe boot le name provided by DHCP. Read-only.

net_pxe_dhcp_server_nameThe name o the DHCP server responsible or these boot parameters. Read-only.

pxe_blksizeThe PXE transer block size. Read-write, deaults to 512.

pxe_default_serverThe deault PXE server. Read-write, although setting this is only useul beoreopening a PXE device.


42/106


pxe_default_gatewayThe deault gateway to use when contacting the PXE server. Read-write, al-though setting this is only useul beore opening a PXE device.


43/106

Chapter 8: Using GRUB via a serial line 35

8 Using GRUB via a serial line

This chapter describes how to use the serial terminal support in GRUB.

I you have many computers or computers with no display/keyboard, it could be veryuseul to control the computers through serial communications. To connect one computerwith another via a serial line, you need to prepare a null-modem (cross) serial cable, andyou may need to have multiport serial boards, i your computer doesnt have extra serialports. In addition, a terminal emulator is also required, such as minicom. Reer to a manualo your operating system, or more inormation.

As or GRUB, the instruction to set up a serial terminal is quite simple. Here is anexample:

grub> serial --unit=0 --speed=9600

grub> terminal_input serial; terminal_output serial

The command serial initializes the serial unit 0 with the speed 9600bps. The serial

unit 0 is usually called COM1, so, i you want to use COM2, you must speciy --unit=1instead. This command accepts many other options, so please reer to Section 14.2.1 [serial],page 52, or more details.

The commands terminal_input (see Section 14.2.2 [terminal input], page 52) andterminal_output (see Section 14.2.3 [terminal output], page 52) choose which type oterminal you want to use. In the case above, the terminal will be a serial terminal, butyou can also pass console to the command, as terminal_input serial console. In thiscase, a terminal in which you press any key will be selected as a GRUB terminal. In theexample above, note that you need to put both commands on the same command line, asyou will lose the ability to type commands on the console ater the rst command.

However, note that GRUB assumes that your terminal emulator is compatible with

VT100 by deault. This is true or most terminal emulators nowadays, but you should passthe option --dumb to the command i your terminal emulator is not VT100-compatible orimplements ew VT100 escape sequences. I you speciy this option then GRUB providesyou with an alternative menu interace, because the normal menu requires several ancyeatures o your terminal.


44/106


45/106


46/106


47/106

Chapter 10: GRUB image les 39

10 GRUB image les

GRUB consists o several images: a variety o bootstrap images or starting GRUB in

various ways, a kernel image, and a set o modules which are combined with the kernelimage to orm a core image. Here is a short overview o them.

boot.imgOn PC BIOS systems, this image is the rst part o GRUB to start. It is writtento a master boot record (MBR) or to the boot sector o a partition. Because aPC boot sector is 512 bytes, the size o this image is exactly 512 bytes.

The sole unction o boot.img is to read the rst sector o the core image roma local disk and jump to it. Because o the size restriction, boot.img cannotunderstand any le system structure, so grub-setup hardcodes the location othe rst sector o the core image into boot.img when installing GRUB.

diskboot.imgThis image is used as the rst sector o the core image when booting rom ahard disk. It reads the rest o the core image into memory and starts the kernel.Since le system handling is not yet available, it encodes the location o thecore image using a block list ormat.

cdboot.imgThis image is used as the rst sector o the core image when booting rom aCD-ROM drive. It perorms a similar unction to diskboot.img.

pxeboot.imgThis image is used as the start o the core image when booting rom the networkusing PXE. See Chapter 7 [Network], page 33.

lnxboot.imgThis image may be placed at the start o the core image in order to makeGRUB look enough like a Linux kernel that it can be booted by LILO using animage= section.

kernel.imgThis image contains GRUBs basic run-time acilities: rameworks or deviceand le handling, environment variables, the rescue mode command-line parser,and so on. It is rarely used directly, but is built into all core images.

core.imgThis is the core image o GRUB. It is built dynamically rom the kernel image

and an arbitrary list o modules by the grub-mkimage program. Usually, itcontains enough modules to access /boot/grub, and loads everything else(including menu handling, the ability to load target operating systems, and soon) rom the le system at run-time. The modular design allows the core imageto be kept small, since the areas o disk where it must be installed are oten assmall as 32KB.

See Section 3.4 [BIOS installation], page 11, or details on where the core imagecan be installed on PC systems.


48/106


*.mod Everything else in GRUB resides in dynamically loadable modules. These areoten loaded automatically, or built into the core image i they are essential, butmay also be loaded manually using the insmod command (see Section 14.3.22[insmod], page 57).

For GRUB Legacy users

GRUB 2 has a diferent design rom GRUB Legacy, and so correspondences with the imagesit used cannot be exact. Nevertheless, GRUB Legacy users oten ask questions in the termsthey are amiliar with, and so here is a brie guide to how GRUB 2s images relate to that.

stage1 Stage 1 rom GRUB Legacy was very similar to boot.img in GRUB 2, andthey serve the same unction.

*_stage1_5In GRUB Legacy, Stage 1.5s unction was to include enough lesystem code toallow the much larger Stage 2 to be read rom an ordinary lesystem. In this

respect, its unction was similar to core.img in GRUB 2. However, core.imgis much more capable than Stage 1.5 was; since it ofers a rescue shell, it issometimes possible to recover manually in the event that it is unable to loadany other modules, or example i partition numbers have changed. core.imgis built in a more exible way, allowing GRUB 2 to support reading modulesrom advanced disk types such as LVM and RAID.

GRUB Legacy could run with only Stage 1 and Stage 2 in some limited cong-urations, while GRUB 2 requires core.img and cannot work without it.

stage2 GRUB 2 has no single Stage 2 image. Instead, it loads modules rom/boot/grub at run-time.

stage2_eltoritoIn GRUB 2, images or booting rom CD-ROM drives are now constructedusing cdboot.img and core.img, making sure that the core image containsthe iso9660 module. It is usually best to use the grub-mkrescue program orthis.

nbgrub There is as yet no equivalent or nbgrub in GRUB 2; it was used by Etherbootand some other network boot loaders.

pxegrub In GRUB 2, images or PXE network booting are now constructed usingpxeboot.img and core.img, making sure that the core image contains thepxe and pxecmd modules. See Chapter 7 [Network], page 33.


49/106

Chapter 11: Filesystem syntax and semantics 41

11 Filesystem syntax and semantics

GRUB uses a special syntax or speciying disk drives which can be accessed by BIOS.

Because o BIOS limitations, GRUB cannot distinguish between IDE, ESDI, SCSI, or others.You must know yoursel which BIOS device is equivalent to which OS device. Normally, thatwill be clear i you see the les in a device or use the command search (see Section 14.3.40[search], page 61).

11.1 How to speciy devices

The device syntax is like this:

(device [,part-num][,bsd-subpart-letter])

[] means the parameter is optional. device should be either fd or hd ollowedby a digit, like fd0. But you can also set device to a hexadecimal or a decimal number

which is a BIOS drive number, so the ollowing are equivalent:(hd0)

(0x80)

(128)

part-num represents the partition number o device, starting rom one or primarypartitions and rom ve or extended partitions, and bsd-subpart-letter represents the BSDdisklabel subpartition, such as a or e.

A shortcut or speciying BSD subpartitions is (device,bsd-subpart-letter), inthis case, GRUB searches or the rst PC partition containing a BSD disklabel, then ndsthe subpartition bsd-subpart-letter. Here is an example:

(hd0,a)The syntax (hd0) represents using the entire disk (or the MBR when installing

GRUB), while the syntax (hd0,1) represents using the rst partition o the disk (or theboot sector o the partition when installing GRUB).

I you enabled the network support, the special drive (pxe) is also available. Beoreusing the network drive, you must initialize the network. See Chapter 7 [Network], page 33,or more inormation.

I you boot GRUB rom a CD-ROM, (cd) is available. See Section 3.2 [Making aGRUB bootable CD-ROM], page 10, or details.

11.2 How to speciy lesThere are two ways to speciy les, by absolute fle name and by block list.

An absolute le name resembles a Unix absolute le name, using / or the directoryseparator (not \ as in DOS). One example is (hd0,1)/boot/grub/grub.cfg. This meansthe le /boot/grub/grub.cfg in the rst partition o the rst hard disk. I you omit thedevice name in an absolute le name, GRUB uses GRUBs root device implicitly. Soi you set the root device to, say, (hd1,1) by the command set root=(hd1,1) (seeSection 14.3.42 [set], page 64), then /boot/kernel is the same as (hd1,1)/boot/kernel.


50/106


11.3 How to speciy block lists

A block list is used or speciying a le that doesnt appear in the lesystem, like a chain-loader. The syntax is [offset ]+length [,[offset ]+length ].... Here is an example:

0+100,200+1,300+300This represents that GRUB should read blocks 0 through 99, block 200, and blocks

300 through 599. I you omit an ofset, then GRUB assumes the ofset is zero.

Like the le name syntax (see Section 11.2 [File name syntax], page 41), i a blocklistdoes not contain a device name, then GRUB uses GRUBs root device. So (hd0,2)+1 isthe same as +1 when the root device is (hd0,2).


51/106

Chapter 12: GRUBs user interace 43

12 GRUBs user interace

GRUB has both a simple menu interace or choosing preset entries rom a congurationle, and a highly exible command-line or perorming any desired combination o bootcommands.

GRUB looks or its conguration le as soon as it is loaded. I one is ound, then theull menu interace is activated using whatever entries were ound in the le. I you choosethe command-line menu option, or i the conguration le was not ound, then GRUB dropsto the command-line interace.

12.1 The exible command-line interace

The command-line interace provides a prompt and ater it an editable text area much like acommand-line in Unix or DOS. Each command is immediately executed ater it is entered1.The commands (see Section 14.3 [Command-line and menu entry commands], page 53) area subset o those available in the conguration le, used with exactly the same syntax.

Cursor movement and editing o the text on the line can be done via a subset o theunctions available in the Bash shell:

C-FPC RIGHT KEY

Move orward one character.

C-BPC LEFT KEY

Move back one character.

C-AHOME Move to the start o the line.

C-EEND Move the the end o the line.

C-DDEL Delete the character underneath the cursor.

C-HBS Delete the character to the let o the cursor.

C-K Kill the text rom the current cursor position to the end o the line.

C-U Kill backward rom the cursor to the beginning o the line.

C-Y Yank the killed text back into the bufer at the cursor.

C-PPC UP KEY

Move up through the history list.

C-NPC DOWN KEY

Move down through the history list.

1 However, this behavior will be changed in the uture version, in a user-invisible way.


52/106


When typing commands interactively, i the cursor is within or beore the rst wordin the command-line, pressing the TAB key (or C-I) will display a listing o the availablecommands, and i the cursor is ater the rst word, the TAB will provide a completionlisting o disks, partitions, and le names depending on the context. Note that to obtain alist o drives, one must open a parenthesis, as root (.

Note that you cannot use the completion unctionality in the TFTP lesystem. Thisis because TFTP doesnt support le name listing or the security.

12.2 The simple menu interace

The menu interace is quite easy to use. Its commands are both reasonably intuitive anddescribed on screen.

Basically, the menu interace provides a list o boot entries to the user to chooserom. Use the arrow keys to select the entry o choice, then press RET to run it. Anoptional timeout is available to boot the deault entry (the rst one i not set), which is

aborted by pressing any key.Commands are available to enter a bare command-line by pressing C (which operates

exactly like the non-cong-le version o GRUB, but allows one to return to the menu idesired by pressing ESC) or to edit any o the boot entries by pressing E.

I you protect the menu interace with a password (see Chapter 15 [Security],page 65), all you can do is choose an entry by pressing RET, or press P to enter thepassword.

12.3 Editing a menu entry

The menu entry editor looks much like the main menu interace, but the lines in the menuare individual commands in the selected entry instead o entry names.

I an ESC is pressed in the editor, it aborts all the changes made to the congurationentry and returns to the main menu interace.

Each line in the menu entry can be edited reely, and you can add new lines bypressing RET at the end o a line. To boot the edited entry, press CTRL-X.

Although GRUB unortunately does not support undo, you can do almost the samething by just returning to the main menu using ESC.


53/106

Chapter 13: GRUB environment variables 45

13 GRUB environment variables

GRUB supports environment variables which are rather like those ofered by all Unix-

like systems. Environment variables have a name, which is unique and is usually a shortidentier, and a value, which is an arbitrary string o characters. They may be set (seeSection 14.3.42 [set], page 64), unset (see Section 14.3.44 [unset], page 64), or looked up(see Section 5.2 [Shell-like scripting], page 20) by name.

A number o environment variables have special meanings to various parts o GRUB.Others may be used reely in GRUB conguration les.

13.1 Special environment variables

These variables have special meaning to GRUB.

13.1.1 biosnum

When chain-loading another boot loader (see Section 4.1.2 [Chain-loading], page 13),GRUB may need to know what BIOS drive number corresponds to the root device (seeSection 13.1.29 [root], page 49) so that it can set up registers properly. I the biosnumvariable is set, it overrides GRUBs own means o guessing this.

For an alternative approach which also changes BIOS drive mappings or the chain-loaded system, see Section 14.3.12 [drivemap], page 55.

13.1.2 chosen

When executing a menu entry, GRUB sets the chosen variable to the title o the entry beingexecuted.

I the menu entry is in one or more submenus, then chosen is set to the titles o each

o the submenus starting rom the top level ollowed by the title o the menu entry itsel,separated by >.

13.1.3 color highlight

This variable contains the highlight oreground and background terminal colors, separatedby a slash (/). Setting this variable changes those colors. For the available color names,see Section 13.1.4 [color normal], page 45.

The deault is black/white.

13.1.4 color normal

This variable contains the normal oreground and background terminal colors, separated

by a slash (/). Setting this variable changes those colors. Each color must be a name romthe ollowing list:

black

blue

green

cyan

red


54/106


magenta

brown

light-gray

dark-gray

light-blue

light-green

light-cyan

light-red

light-magenta

yellow

white

The deault is white/black.

13.1.5 debug

This variable may be set to enable debugging output rom various components o GRUB.The value is a list o debug acility names separated by whitespace or ,, or all to enableall available debugging output.

13.1.6 deault

I this variable is set, it identies a menu entry that should be selected by deault, possiblyater a timeout (see Section 13.1.32 [timeout], page 49). The entry may be identied bynumber or by title.

I the entry is in a submenu, then it must be identied using the titles o each othe submenus starting rom the top level ollowed by the number or title o the menu entryitsel, separated by >. For example, take the ollowing menu structure:

Submenu 1

Menu Entry 1

Menu Entry 2

Submenu 2

Submenu 3

Menu Entry 3

Menu Entry 4

Menu Entry 5

Menu Entry 3 would then be identied as Submenu 2>Submenu 3>Menu Entry 3.This variable is oten set by GRUB_DEFAULT (see Section 5.1 [Simple conguration],

page 17), grub-set-default, or grub-reboot.

13.1.7 allback

I this variable is set, it identies a menu entry that should be selected i the deault menuentry ails to boot. Entries are identied in the same way as or default (see Section 13.1.6[deault], page 46).


55/106


56/106


grub-mkconfig (see Section 5.1 [Simple conguration], page 17) will set a reason-able deault or this variable i internationalization is needed and any translation les areavailable.

13.1.14 menu color highlightThis variable contains the oreground and background colors to be used or the highlightedmenu entry, separated by a slash (/). Setting this variable changes those colors. For theavailable color names, see Section 13.1.4 [color normal], page 45.

The deault is the value o color_highlight (see Section 13.1.3 [color highlight],page 45).

13.1.15 menu color normal

This variable contains the oreground and background colors to be used or non-highlightedmenu entries, separated by a slash (/). Setting this variable changes those colors. For theavailable color names, see Section 13.1.4 [color normal], page 45.

The deault is the value o color_normal (see Section 13.1.4 [color normal],page 45).

13.1.16 net pxe boot le

See Chapter 7 [Network], page 33.

13.1.17 net pxe dhcp server name


13.1.18 net pxe domain


13.1.19 net pxe extensionspath


13.1.20 net pxe hostname


13.1.21 net pxe ip


13.1.22 net pxe mac


13.1.23 net pxe rootpath


13.1.24 pager

I set to 1, pause output ater each screenul and wait or keyboard input. The deault isnot to pause output.


57/106

Chapter 13: GRUB environment variables 49

13.1.25 prex

The location o the /boot/grub directory as an absolute le name (see Section 11.2 [Filename syntax], page 41). This is normally set by GRUB at startup based on inormation

provided by grub-install. GRUB modules are dynamically loaded rom this directory, soit must be set correctly in order or many parts o GRUB to work.

13.1.26 pxe blksize


13.1.27 pxe deault gateway


13.1.28 pxe deault server


13.1.29 root

The root device name (see Section 11.1 [Device syntax], page 41). Any le names that donot speciy an explicit device name are read rom this device. The deault is normally setby GRUB at startup based on the value o prefix (see Section 13.1.25 [prex], page 49).

For example, i GRUB was installed to the rst partition o the rst hard disk, thenprefix might be set to (hd0,msdos1)/boot/grub and root to hd0,msdos1.

13.1.30 superusers

This variable may be set to a list o superuser names to enable authentication support. SeeChapter 15 [Security], page 65.

13.1.31 theme

This variable may be set to a directory containing a GRUB graphical menu theme. SeeChapter 6 [Theme le ormat], page 25.

This variable is oten set by GRUB_THEME (see Section 5.1 [Simple conguration],page 17).

13.1.32 timeout

I this variable is set, it species the time in seconds to wait or keyboard input beore boot-ing the deault menu entry. A timeout o 0 means to boot the deault entry immediatelywithout displaying the menu; a timeout o -1 (or unset) means to wait indenitely.

This variable is oten set by GRUB_TIMEOUT o r GRUB_HIDDEN_TIMEOUT (seeSection 5.1 [Simple conguration], page 17).

13.2 The GRUB environment block

It is oten useul to be able to remember a small amount o inormation rom one boot to thenext. For example, you might want to set the deault menu entry based on what was selectedthe last time. GRUB deliberately does not implement support or writing les in order tominimise the possibility o the boot loader being responsible or le system corruption, so


58/106


a GRUB conguration le cannot just create a le in the ordinary way. However, GRUBprovides an environment block which can be used to save a small amount o state.

The environment block is a preallocated 1024-byte le, which normally lives in

/boot/grub/grubenv

(although you should not assume this). At boot time, theload_

env command (see Section 14.3.27 [load env], page 58) loads environment variables romit, and the save_env (see Section 14.3.39 [save env], page 60) command saves environmentvariables to it. From a running system, the grub-editenv utility can be used to edit theenvironment block.

For saety reasons, this storage is only available when installed on a plain disk (noLVM or RAID), using a non-checksumming lesystem (no ZFS), and using BIOS or EFIunctions (no ATA, USB or IEEE1275).

grub-mkconfig uses this acility to implement GRUB_SAVEDEFAULT (see Section 5.1[Simple conguration], page 17).


59/106

Chapter 14: The list o available commands 51

14 The list o available commands

In this chapter, we list all commands that are available in GRUB.

Commands belong to diferent groups. A ew can only be used in the global sectiono the conguration le (or menu); most o them can be entered on the command-lineand can be used either anywhere in the menu or specically in the menu entries.

In rescue mode, only the insmod (see Section 14.3.22 [insmod], page 57), ls (seeSection 14.3.29 [ls], page 58), set (see Section 14.3.42 [set], page 64), and unset (seeSection 14.3.44 [unset], page 64) commands are normally available. I you end up in rescuemode and do not know what to do, then see Section 18.1 [GRUB only ofers a rescue shell],page 73.

14.1 The list o commands or the menu only

The semantics used in parsing the conguration le are the ollowing:

The les must be in plain-text ormat. # at the beginning o a line in a conguration le means it is only a comment.

Options are separated by spaces.

All numbers can be either decimal or hexadecimal. A hexadecimal number must bepreceded by 0x, and is case-insensitive.

These commands can only be used in the menu:

14.1.1 menuentry

[Command]menuentry title [--class=class . . . ] [--users=users][--hotkey=key] { command ; . . . }

This denes a GRUB menu entry named title. When this entry is selected rom themenu, GRUB will set the chosen environment variable to title, execute the list o com-mands given within braces, and i the last command in the list returned successullyand a kernel was loaded it will execute the boot command.

The --class option may be used any number o times to group menu entries intoclasses. Menu themes may display diferent classes using diferent styles.

The --users option grants specic users access to specic menu entries. SeeChapter 15 [Security], page 65.

The --hotkey option associates a hotkey with a menu entry. key may be a singleletter, or one o the aliases backspace, tab, or delete.

14.1.2 submenu

[Command]submenu title [--class=class . . . ] [--users=users][--hotkey=key] { menu entries . . . }

This denes a submenu. An entry called title will be added to the menu; when thatentry is selected, a new menu will be displayed showing all the entries within thissubmenu.

All options are the same as in the menuentry command (see Section 14.1.1 [menuen-try], page 51).


60/106


14.2 The list o general commands

Commands usable anywhere in the menu and in the command-line.

14.2.1 serial[Command]serial [--unit=unit] [--port=port] [--speed=speed]

[--word=word] [--parity=parity] [--stop=stop]Initialize a serial device. unit is a number in the range 0-3 speciying which serialport to use; deault is 0, which corresponds to the port oten called COM1. port isthe I/O port where the UART is to be ound; i specied it takes precedence overunit. speed is the transmission speed; deault is 9600. word and stop are the numbero data bits and stop bits. Data bits must be in the range 5-8 and stop bits must be1 or 2. Deault is 8 data bits and one stop bit. parity is one o no, odd, even anddeaults to no.

The serial port is not used as a communication channel unless the terminal_input

or terminal_output command is used (see Section 14.2.2 [terminal input], page 52,see Section 14.2.3 [terminal output], page 52).

See also Chapter 8 [Serial terminal], page 35.

14.2.2 terminal input

[Command]terminal_input [--append|--remove] [terminal1] [terminal2] . . .List or select an input terminal.

With no arguments, list the active and available input terminals.

With --append, add the named terminals to the list o active input terminals; anyo these may be used to provide input to GRUB.

With --remove, remove the named terminals rom the active list.With no options but a list o terminal names, make only the listed terminal namesactive.

14.2.3 terminal output

[Command]terminal_output [--append|--remove] [terminal1] [terminal2] . . .List or select an output terminal.

With no arguments, list the active and available output terminals.

With --append, add the named terminals to the list o active output terminals; allo these will receive output rom GRUB.

With --remove, remove the named terminals rom the active list.With no options but a list o terminal names, make only the listed terminal namesactive.

14.2.4 termino

[Command]terminfo [-a|-u|-v] [term]Dene the capabilities o your terminal by giving the name o an entry in the terminodatabase, which should correspond roughly to a TERM environment variable in Unix.


61/106


The currently available terminal types are vt100, vt100-color, ieee1275, anddumb. I you need other terminal types, please contact us to discuss the best way toinclude support or these in GRUB.

The -a (--ascii), -u (--utf8), and -v (--visual-utf8) options controlhow non-ASCII text is displayed. -a species an ASCII-only terminal; -u spec-ies logically-ordered UTF-8; and -v species "visually-ordered UTF-8" (in otherwords, arranged such that a terminal emulator without bidirectional text support willdisplay right-to-let text in the proper order; this is not really proper UTF-8, but aworkaround).

I no option or terminal type is specied, the current terminal type is printed.

14.3 The list o command-line and menu entry commands

These commands are usable in the command-line and in menu entries. I you orget acommand, you can run the command help (see Section 14.3.19 [help], page 57).

14.3.1 acpi

[Command]acpi [-1|-2][--exclude=table1,...|--load-only=table1,...] [--oemid=id][--oemtable=table] [--oemtablerev=rev][--oemtablecreator=creator] [--oemtablecreatorrev=rev][--no-ebda] flename . . .

Modern BIOS systems normally implement the Advanced Conguration and PowerInterace (ACPI), and dene various tables that describe the interace between anACPI-compliant operating system and the rmware. In some cases, the tables pro-vided by deault only work well with certain operating systems, and it may be neces-

sary to replace some o them.Normally, this command will replace the Root System Description Pointer (RSDP) inthe Extended BIOS Data Area to point to the new tables. I the --no-ebda optionis used, the new tables will be known only to GRUB, but may be used by GRUBsEFI emulation.

14.3.2 badram

[Command]badram addr,mask[,addr,mask...]Filter out bad RAM.

This command noties the memory manager that specied regions o RAM ought tobe ltered out (usually, because theyre damaged). This remains in efect ater a payload

kernel has been loaded by GRUB, as long as the loaded kernel obtains its memory maprom GRUB. Kernels that support this include Linux, GNU Mach, the kernel o FreeBSDand Multiboot kernels in general.

Syntax is the same as provided by the Memtest86+ utility: a list o address/maskpairs. Given a page-aligned address and a base address / mask pair, i all the bits o thepage-aligned address that are enabled by the mask match with the base address, it meansthis page is to be ltered. This syntax makes it easy to represent patterns that are otenresult o memory damage, due to physical distribution o memory cells.
http://www.memtest.org/http://www.memtest.org/http://www.memtest.org/http://www.memtest.org/


62/106


14.3.3 blocklist

[Command]blocklist flePrint a block list (see Section 11.3 [Block list syntax], page 42) or fle.

14.3.4 boot

[Command]bootBoot the OS or chain-loader which has been loaded. Only necessary i running theully interactive command-line (it is implicit at the end o a menu entry).

14.3.5 cat

[Command]cat [--dos] fleDisplay the contents o the le fle. This command may be useul to remind you oyour OSs root partition:

grub> cat /etc/fstab

I the --dos option is used, then carriage return / new line pairs will be displayedas a simple new line. Otherwise, the carriage return will be displayed as a controlcharacter () to make it easier to see when boot problems are caused by a leormatted using DOS-style line endings.

14.3.6 chainloader

[Command]chainloader [--force] fleLoad fle as a chain-loader. Like any other le loaded by the lesystem code, it can

use the blocklist notation (see Section 11.3 [Block list syntax], page 42) to grab therst sector o the current partition with +1. I you speciy the option --force, thenload fle orcibly, whether it has a correct signature or not. This is required when youwant to load a deective boot loader, such as SCO UnixWare 7.1.

14.3.7 cmp

[Command]cmp fle1 fle2Compare the le fle1 with the le fle2. I they difer in size, print the sizes like this:

Differ in size: 0x1234 [foo], 0x4321 [bar]

I the sizes are equal but the bytes at an ofset difer, then print the bytes like this:

Differ at the offset 777: 0xbe [foo], 0xef [bar]

I they are completely identical, nothing will be printed.

14.3.8 congle

[Command]configfile fleLoad fle as a conguration le. I fle denes any menu entries, then show a menucontaining them immediately.


63/106


64/106


\f orm eed

\n new line

\r carriage return

\t horizontal tab

\v vertical tab

When interpreting backslash escapes, backslash ollowed by any other character willprint that character.

14.3.14 export

[Command]export envvarExport the environment variable envvar. Exported variables are visible to subsidiaryconguration les loaded using configfile.

14.3.15 alse

[Command]falseDo nothing, unsuccessully. This is mainly useul in control constructs such as if andwhile (see Section 5.2 [Shell-like scripting], page 20).

14.3.16 gettext

[Command]gettext stringTranslate string into the current language.

The current language code is stored in the lang variable in GRUBs environment(see Section 13.1.12 [lang], page 47). Translation les in MO ormat areread rom locale_dir (see Section 13.1.13 [locale dir], page 47), usually

/boot/grub/locale.

14.3.17 gptsync

[Command]gptsync device [partition[+/-[type]]] . . .Disks using the GUID Partition Table (GPT) also have a legacy Master Boot Record(MBR) partition table or compatibility with the BIOS and with older operatingsystems. The legacy MBR can only represent a limited subset o GPT partitionentries.

This command populates the legacy MBR with the specied partition entries ondevice. Up to three partitions may be used.

type is an MBR partition type code; prex with 0x i you want to enter this in

hexadecimal. The separator between partition and type may be + to make thepartition active, or - to make it inactive; only one partition may be active. I boththe separator and type are omitted, then the partition will be inactive.

14.3.18 halt

[Command]halt --no-apmThe command halts the computer. I the --no-apm option is specied, no APMBIOS call is perormed. Otherwise, the computer is shut down using APM.


65/106


14.3.19 help

[Command]help [pattern . . . ]Display helpul inormation about builtin commands. I you do not speciy pattern,

this command shows short descriptions o all available commands.I you speciy any patterns, it displays longer inormation about each o the commandswhose names begin with those patterns.

14.3.20 initrd

[Command]initrd fleLoad an initial ramdisk or a Linux kernel image, and set the appropriate param-eters in the Linux setup area in memory. This may only be used ater the linuxcommand (see Section 14.3.24 [linux], page 57) has been run. See also Section 4.2.2[GNU/Linux], page 14.

14.3.21 initrd16

[Command]initrd16 fleLoad an initial ramdisk or a Linux kernel image to be booted in 16-bit mode, andset the appropriate parameters in the Linux setup area in memory. This may onlybe used ater the linux16 command (see Section 14.3.25 [linux16], page 58) has beenrun. See also Section 4.2.2 [GNU/Linux], page 14.

This command is only available on x86 systems.

14.3.22 insmod

[Command]insmod moduleInsert the dynamic GRUB module called module.

14.3.23 keystatus

[Command]keystatus [--shift] [--ctrl] [--alt]Return true i the Shit, Control, or Alt modier keys are held down, as requested byoptions. This is useul in scripting, to allow some user control over behaviour withouthaving to wait or a keypress.

Checking key modier status is only supported on some platorms. I invoked withoutany options, the keystatus command returns true i and only i checking key modierstatus is supported.

14.3.24 linux

[Command]linux fle . . .Load a Linux kernel image rom fle. The rest o the line is passed verbatim as thekernel command-line. Any initrd must be reloaded ater usin

Grub Manual

Documents

Transcript of Grub Manual