Grub
Grub
This manual is for GNU GRUB (version 2.00, 23 June 2012). Copyright c 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections.
Table of Contents
1 Introduction to GRUB . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 1.2 1.3 1.4 1.5 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . History of GRUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dierences from previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GRUB features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The role of a boot loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 2 3 5
2 3
Booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1 How to boot operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 How to boot an OS directly with GRUB . . . . . . . . . . . . . . . . . . 4.1.2 Chain-loading an OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Loopback booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Some caveats on OS-specic issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 GNU/Hurd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.2 GNU/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.3 DOS/Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 13 13 14 14 14 14 15
Theme le format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.1 6.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Theme Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.1 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.2 Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.3 Progress Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.4 Circular Progress Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.5 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.6 Boot Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.7 Styled Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 27 27 27 27 27 28 28 28
ii
GNU GRUB Manual 2.00 6.2.8 Creating Styled Box Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Theme File Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.1 Global Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.3 Global Property List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.4 Component Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.5 Component List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.6 Common properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 29 29 29 29 30 30 33
6.3
7 8 9 10 11
Booting GRUB from the network . . . . . . . . . . . . 35 Using GRUB via a serial line . . . . . . . . . . . . . . . . . 37 Using GRUB with vendor power-on keys . . . 39 GRUB image les . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Filesystem syntax and semantics . . . . . . . . . . . . 43
How to specify devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 How to specify les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 How to specify block lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
12
13
13.1 Special environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.1 biosnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.2 chosen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.3 color highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.4 color normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.5 debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.6 default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.7 fallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.8 gfxmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.9 gfxpayload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.10 gfxterm font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.11 icondir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.12 lang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.13 locale dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.14 menu color highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.15 menu color normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.16 net pxe boot le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.1.17 net pxe dhcp server name . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iii 13.1.18 13.1.19 13.1.20 13.1.21 13.1.22 13.1.23 13.1.24 13.1.25 13.1.26 13.1.27 13.1.28 13.1.29 13.1.30 13.1.31 13.1.32 13.2 The net pxe domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . net pxe extensionspath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . net pxe hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . net pxe ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . net pxe mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . net pxe rootpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . prex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pxe blksize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pxe default gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pxe default server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . superusers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GRUB environment block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 50 50 50 50 50 50 51 51 51 51 51 51 51 51 51
14
14.1 The 14.1.1 14.1.2 14.2 The 14.2.1 14.2.2 14.2.3 14.2.4 14.3 The 14.3.1 14.3.2 14.3.3 14.3.4 14.3.5 14.3.6 14.3.7 14.3.8 14.3.9 14.3.10 14.3.11 14.3.12 14.3.13 14.3.14 14.3.15 14.3.16 14.3.17 14.3.18 14.3.19 14.3.20 14.3.21
iv 14.3.22 14.3.23 14.3.24 14.3.25 14.3.26 14.3.27 14.3.28 14.3.29 14.3.30 14.3.31 14.3.32 14.3.33 14.3.34 14.3.35 14.3.36 14.3.37 14.3.38 14.3.39 14.3.40 14.3.41 14.3.42 14.3.43 14.3.44 14.3.45
GNU GRUB Manual 2.00 insmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . keystatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . linux16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . load env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loopback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . normal exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . parttool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password pbkdf2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pxe unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uppermem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 59 60 60 60 60 60 61 61 61 61 62 62 62 62 62 62 63 63 63 66 66 66 66
15 16 17 18 19 20 21 22 23 24
Charset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Filesystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Output terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Input terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Regexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Other . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Authentication and authorisation . . . . . . . . . . . 81 Platform limitations . . . . . . . . . . . . . . . . . . . . . . . . . 83 Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
25 26 27 28 29 30 31 32
27.1
Invoking grub-install . . . . . . . . . . . . . . . . . . . . . . . . . 97 Invoking grub-mkcong . . . . . . . . . . . . . . . . . . . . . . 99 Invoking grub-mkpasswd-pbkdf2 . . . . . . . . . . 101 Invoking grub-mkrescue . . . . . . . . . . . . . . . . . . . . 103 Invoking grub-probe . . . . . . . . . . . . . . . . . . . . . . . . 105
Appendix A How to obtain and build GRUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Appendix B Appendix C Appendix D Reporting bugs . . . . . . . . . . . . . . . . . . 109 Where GRUB will go . . . . . . . . . . . 111 Copying This Manual . . . . . . . . . . . 113
D.1 GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 D.1.1 ADDENDUM: How to use this License for your documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
1 Introduction to GRUB
1.1 Overview
Briey, a boot loader is the rst software program that runs when a computer starts. It is responsible for loading and transferring control to an operating system kernel software (such as Linux or GNU Mach). The kernel, in turn, initializes the rest of the operating system (e.g. a GNU system). GNU GRUB is a very powerful boot loader, which can load a wide variety of free operating systems, as well as proprietary operating systems with chain-loading1 . GRUB is designed to address the complexity of booting a personal computer; both the program and this manual are tightly bound to that computer platform, although porting to other platforms may be addressed in the future. One of the important features in GRUB is exibility; GRUB understands lesystems and kernel executable formats, so you can load an arbitrary operating system the way you like, without recording the physical position of your kernel on the disk. Thus you can load the kernel just by specifying its le name and the drive and partition where the kernel resides. When booting with GRUB, you can use either a command-line interface (see Section 12.1 [Command-line interface], page 45), or a menu interface (see Section 12.2 [Menu interface], page 46). Using the command-line interface, you type the drive specication and le name of the kernel manually. In the menu interface, you just select an OS using the arrow keys. The menu is based on a conguration le which you prepare beforehand (see Chapter 5 [Conguration], page 17). While in the menu, you can switch to the command-line mode, and vice-versa. You can even edit menu entries before using them. In the following chapters, you will learn how to specify a drive, a partition, and a le name (see Chapter 2 [Naming convention], page 7) to GRUB, how to install GRUB on your drive (see Chapter 3 [Installation], page 9), and how to boot your OSes (see Chapter 4 [Booting], page 13), step by step.
chain-load is the mechanism for loading unsupported operating systems by loading another boot loader. It is typically used for loading DOS or Windows.
Yoshinori K. Okuji adopted GRUB as an ocial GNU package, and opened its development by making the latest sources available via anonymous CVS. See Appendix A [Obtaining and Building GRUB], page 107, for more information. Over the next few years, GRUB was extended to meet many needs, but it quickly became clear that its design was not keeping up with the extensions being made to it, and we reached the point where it was very dicult to make any further changes without breaking existing features. Around 2002, Yoshinori K. Okuji started work on PUPA (Preliminary Universal Programming Architecture for GNU GRUB), aiming to rewrite the core of GRUB to make it cleaner, safer, more robust, and more powerful. PUPA was eventually renamed to GRUB 2, and the original version of GRUB was renamed to GRUB Legacy. Small amounts of maintenance continued to be done on GRUB Legacy, but the last release (0.97) was made in 2005 and at the time of writing it seems unlikely that there will be another. By around 2007, GNU/Linux distributions started to use GRUB 2 to limited extents, and by the end of 2009 multiple major distributions were installing it by default.
GRUB 2s interface can be translated, including menu entry names. The image les (see Chapter 10 [Images], page 41) that make up GRUB have been reorganised; Stage 1, Stage 1.5, and Stage 2 are no more. GRUB 2 puts many facilities in dynamically loaded modules, allowing the core image to be smaller, and allowing the core image to be built in more exible ways.
Have a exible command-line interface A fairly exible command-line interface, accessible from the menu, is available to edit any preset commands, or write a new boot command set from scratch. If no conguration le is present, GRUB drops to the command-line. The list of commands (see Chapter 14 [Commands], page 53) are a subset of those supported for conguration les. Editing commands closely resembles the Bash command-line (see Section 12.1 [Command-line interface], page 45), with TAB-completion of commands, devices, partitions, and les in a directory depending on context. Support multiple lesystem types Support multiple lesystem types transparently, plus a useful explicit blocklist notation. The currently supported lesystem types are Amiga Fast FileSystem (AFFS), AtheOS fs, BeFS, BtrFS (including raid0, raid1, raid10, gzip and lzo), cpio (little- and big-endian bin, odc and newc variants), Linux ext2/ext3/ext4, DOS FAT12/FAT16/FAT32, exFAT, HFS, HFS+, ISO9660 (including Joliet, Rock-ridge and multi-chunk les), JFS, Minix fs (versions 1, 2 and 3), nilfs2, NTFS (including compression), ReiserFS, ROMFS, Amiga Smart FileSystem (SFS), Squash4, tar, UDF, BSD UFS/UFS2, XFS, and ZFS (including lzjb, gzip, zle, mirror, stripe, raidz1/2/3 and encryption in AES-CCM and AESGCM). See Chapter 11 [Filesystem], page 43, for more information. Support automatic decompression Can decompress les which were compressed by gzip or xz2 . This function is both automatic and transparent to the user (i.e. all functions operate upon the uncompressed contents of the specied les). This greatly reduces a le size and loading time, a particularly great benet for oppies.3 It is conceivable that some kernel modules should be loaded in a compressed state, so a dierent module-loading command can be specied to avoid uncompressing the modules. Access data on any installed device Support reading data from any or all oppies or hard disk(s) recognized by the BIOS, independent of the setting of the root device. Be independent of drive geometry translations Unlike many other boot loaders, GRUB makes the particular drive translation irrelevant. A drive installed and running with one translation may be converted to another translation without any adverse eects or changes in GRUBs conguration. Detect all installed ram GRUB can generally nd all the installed ram on a PC-compatible machine. It uses an advanced BIOS query technique for nding all memory regions. As described on the Multiboot Specication (see Section Motivation in The Multi2 3
Only CRC32 data integrity check is supported (xz default is CRC64 so one should use check=crc32 option). LZMA BCJ lters are supported. There are a few pathological cases where loading a very badly organized ELF kernel might take longer, but in practice this never happen.
boot Specication), not all kernels make use of this information, but GRUB provides it for those who do. Support Logical Block Address mode In traditional disk calls (called CHS mode ), there is a geometry translation problem, that is, the BIOS cannot access over 1024 cylinders, so the accessible space is limited to at least 508 MB and to at most 8GB. GRUB cant universally solve this problem, as there is no standard interface used in all machines. However, several newer machines have the new interface, Logical Block Address (LBA) mode. GRUB automatically detects if LBA mode is available and uses it if available. In LBA mode, GRUB can access the entire disk. Support network booting GRUB is basically a disk-based boot loader but also has network support. You can load OS images from a network by using the TFTP protocol. Support remote terminals To support computers with no console, GRUB provides remote terminal support, so that you can control GRUB from a remote host. Only serial terminal support is implemented at the moment.
The LInux LOader, a boot loader that everybody uses, but nobody likes.
2 Naming convention
The device syntax used in GRUB is a wee bit dierent from what you may have seen before in your operating system(s), and you need to know it so that you can specify a drive/partition. Look at the following examples and explanations: (fd0) First of all, GRUB requires that the device name be enclosed with ( and ). The fd part means that it is a oppy disk. The number 0 is the drive number, which is counted from zero. This expression means that GRUB will use the whole oppy disk. (hd0,msdos2) Here, hd means it is a hard disk drive. The rst integer 0 indicates the drive number, that is, the rst hard disk, the string msdos indicates the partition scheme, while the second integer, 2, indicates the partition number (or the pc slice number in the BSD terminology). The partition numbers are counted from one, not from zero (as was the case in previous versions of GRUB). This expression means the second partition of the rst hard disk drive. In this case, GRUB uses one partition of the disk, instead of the whole disk. (hd0,msdos5) This species the rst extended partition of the rst hard disk drive. Note that the partition numbers for extended partitions are counted from 5, regardless of the actual number of primary partitions on your hard disk. (hd1,msdos1,bsd1) This means the BSD a partition on rst pc slice number of the second hard disk. Of course, to actually access the disks or partitions with GRUB, you need to use the device specication in a command, like set root=(fd0) or parttool (hd0,msdos3) hidden-. To help you nd out which number species a partition you want, the GRUB command-line (see Section 12.1 [Command-line interface], page 45) options have argument completion. This means that, for example, you only need to type set root=( followed by a TAB, and GRUB will display the list of drives, partitions, or le names. So it should be quite easy to determine the name of your target partition, even with minimal knowledge of the syntax. Note that GRUB does not distinguish IDE from SCSI - it simply counts the drive numbers from zero, regardless of their type. Normally, any IDE drive number is less than any SCSI drive number, although that is not true if you change the boot sequence by swapping IDE and SCSI drives in your BIOS. Now the question is, how to specify a le? Again, consider an example: (hd0,msdos1)/vmlinuz This species the le named vmlinuz, found on the rst partition of the rst hard disk drive. Note that the argument completion works with le names, too. That was easy, admit it. Now read the next chapter, to nd out how to actually install GRUB on your drive.
Chapter 3: Installation
3 Installation
In order to install GRUB as your boot loader, you need to rst install the GRUB system and utilities under your UNIX-like operating system (see Appendix A [Obtaining and Building GRUB], page 107). You can do this either from the source tarball, or as a package for your OS. After you have done that, you need to install the boot loader on a drive (oppy or hard disk) by using the utility grub-install (see Chapter 28 [Invoking grub-install], page 97) on a UNIX-like OS. GRUB comes with boot images, which are normally put in the directory /usr/lib/grub/<cpu>-<platform> (for BIOS-based machines /usr/lib/grub/i386-pc). Hereafter, the directory where GRUB images are initially placed (normally /usr/lib/grub/<cpu>-<platform>) will be called the image directory, and the directory where the boot loader needs to nd them (usually /boot) will be called the boot directory.
Some BIOSes have a bug of exposing the rst partition of a USB drive as a oppy instead of exposing the USB drive as a hard disk (they call it USB-FDD boot). In such cases, you need to install like this: # losetup /dev/loop0 /dev/sdb1 # mount /dev/loop0 /mnt/usb # grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0
10
This install doesnt conict with standard install as long as they are in separate directories. Note that grub-install is actually just a shell script and the real task is done by grub-mkimage and grub-setup. Therefore, you may run those commands directly to install GRUB, without using grub-install. Dont do that, however, unless you are very familiar with the internals of GRUB. Installing a boot loader on a running OS may be extremely dangerous.
Chapter 3: Installation
11
(device ) file device is a drive specied in the GRUB syntax (see Section 11.1 [Device syntax], page 43), and le is an OS le, which is normally a device le. Historically, the device map le was used because GRUB device names had to be used in the conguration le, and they were derived from BIOS drive numbers. The map between BIOS drives and OS devices cannot always be guessed correctly: for example, GRUB will get the order wrong if you exchange the boot sequence between IDE and SCSI in your BIOS. Unfortunately, even OS device names are not always stable. Modern versions of the Linux kernel may probe drives in a dierent order from boot to boot, and the prex (/dev/hd* versus /dev/sd*) may change depending on the driver subsystem in use. As a result, the device map le required frequent editing on some systems. GRUB avoids this problem nowadays by using UUIDs or le system labels when generating grub.cfg, and we advise that you do the same for any custom menu entries you write. If the device map le does not exist, then the GRUB utilities will assume a temporary device map on the y. This is often good enough, particularly in the common case of single-disk systems. However, the device map le is not entirely obsolete yet, and it is used for overriding when current environment is dierent from the one on boot. Most common case is if you use a partition or logical volume as a disk for virtual machine. You can put any comments in the le if needed, as the GRUB utilities assume that a line is just a comment if the rst character is #.
12
starts at least 31 KiB (63 sectors) from the start of the disk; on modern disks, it is often a performance advantage to align partitions on larger boundaries anyway, so the rst partition might start 1 MiB from the start of the disk.
GPT
Some newer systems use the GUID Partition Table (GPT) format. This was specied as part of the Extensible Firmware Interface (EFI), but it can also be used on BIOS platforms if system software supports it; for example, GRUB and GNU/Linux can be used in this conguration. With this format, it is possible to reserve a whole partition for GRUB, called the BIOS Boot Partition. GRUB can then be embedded into that partition without the risk of being overwritten by other software and without being contained in a lesystem which might move its blocks around. When creating a BIOS Boot Partition on a GPT system, you should make sure that it is at least 31 KiB in size. (GPT-formatted disks are not usually particularly small, so we recommend that you make it larger than the bare minimum, such as 1 MiB, to allow plenty of room for growth.) You must also make sure that it has the proper partition type. Using GNU Parted, you can set this using a command such as the following: # parted /dev/disk set partition-number bios_grub on If you are using gdisk, set the partition type to 0xEF02. With partitioning programs that require setting the GUID directly, it should be 21686148-6449-6e6f-744e656564454649. Caution: Be very careful which partition you select! When GRUB nds a BIOS Boot Partition during installation, it will automatically overwrite part of it. Make sure that the partition does not contain any other data.
Chapter 4: Booting
13
4 Booting
GRUB can load Multiboot-compliant kernels in a consistent way, but for some free operating systems you need to use some OS-specic magic.
4.1.2 Chain-loading an OS
Operating systems that do not support Multiboot and do not have specic support in GRUB (specic support is available for Linux, FreeBSD, NetBSD and OpenBSD) must be chain-loaded, which involves loading another boot loader and jumping to it in real mode. The chainloader command (see Section 14.3.6 [chainloader], page 56) is used to set this up. It is normally also necessary to load some GRUB modules and set the appropriate root device. Putting this together, we get something like this, for a Windows system on the rst partition of 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.3.3 [DOS/Windows], page 15. Chain-loading is only supported on PC BIOS and EFI platforms.
14
4.3.1 GNU/Hurd
Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is nothing special about it. But do not forget that you have to specify a root partition to the kernel. 1. Set GRUBs root device to the same drive as GNU/Hurds. The command search --set=root --file /boot/gnumach.gz or similar may help you (see Section 14.3.40 [search], page 63). 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 56).
4.3.2 GNU/Linux
It is relatively easy to boot GNU/Linux from GRUB, because it somewhat resembles to boot a Multiboot-compliant OS.
Chapter 4: Booting
15
1. Set GRUBs root device to the same drive as GNU/Linuxs. The command search --set=root --file /vmlinuz or similar may help you (see Section 14.3.40 [search], page 63). 2. Load the kernel using the command linux (see Section 14.3.24 [linux], page 60): grub> linux /vmlinuz root=/dev/sda1 If you need to specify some kernel parameters, just append them to the command. For example, to set acpi to off, do this: grub> linux /vmlinuz root=/dev/sda1 acpi=off See the documentation in the Linux source tree for complete information on the available options. With linux GRUB uses 32-bit protocol. Some BIOS services like APM or EDD arent available with this protocol. In this case you need to use linux16 grub> linux16 /vmlinuz root=/dev/sda1 acpi=off 3. If you use an initrd, execute the command initrd (see Section 14.3.20 [initrd], page 59) after linux: grub> initrd /initrd If you used linux16 you need to use initrd16: grub> initrd16 /initrd 4. Finally, run the command boot (see Section 14.3.4 [boot], page 56). Caution: If you use an initrd and specify the mem= option to the kernel to let it use less than actual memory size, you will also have to specify the same memory size to GRUB. To let GRUB know the size, run the command uppermem before loading the kernel. See Section 14.3.45 [uppermem], page 66, for more information.
4.3.3 DOS/Windows
GRUB cannot boot DOS or Windows directly, so you must chain-load them (see Section 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 functions. If you have installed DOS (or Windows) on a non-rst hard disk, you have to use the disk swapping technique, because that OS cannot boot from any disks but the rst one. The workaround used in GRUB is the command drivemap (see Section 14.3.12 [drivemap], page 57), like this: drivemap -s (hd0) (hd1) This performs a virtual swap between your rst and second hard drive. Caution: This is eective only if DOS (or Windows) uses BIOS to access the swapped disks. If that OS uses a special driver for the disks, this probably wont work. Another problem arises if you installed more than one set of DOS/Windows onto one disk, because they could be confused if there are more than one primary partitions for DOS/Windows. Certainly you should avoid doing this, but there is a solution if you do want to do so. Use the partition hiding/unhiding technique. If GRUB hides a DOS (or Windows) partition (see Section 14.3.32 [parttool], page 61), DOS (or Windows) will ignore the partition. If GRUB unhides a DOS (or
16
Windows) partition, DOS (or Windows) will detect the partition. Thus, if you have installed DOS (or Windows) on the rst and the second partition of the rst hard disk, and you want to boot the copy on the rst partition, do the following: parttool (hd0,1) hiddenparttool (hd0,2) hidden+ set root=(hd0,1) chainloader +1 parttool ${root} boot+ boot
17
18
is useful without this option, in conjunction with grub-set-default or grubreboot. Unset by default. This option relies on the environment block, which may not be available in all situations (see Section 13.2 [Environment block], page 51). GRUB_TIMEOUT Boot the default entry this many seconds after the menu is displayed, unless a key is pressed. The default is 5. Set to 0 to boot immediately without displaying the menu, or to -1 to wait indenitely. GRUB_HIDDEN_TIMEOUT Wait this many seconds for a key to be pressed before displaying the menu. If no key is pressed during that time, display the menu for the number of seconds specied in GRUB TIMEOUT before booting the default entry. We expect that most people who use GRUB HIDDEN TIMEOUT will want to have GRUB TIMEOUT set to 0 so that the menu is not displayed at all unless a key is pressed. Unset by default. GRUB_HIDDEN_TIMEOUT_QUIET In conjunction with GRUB_HIDDEN_TIMEOUT, set this to true to suppress the verbose countdown while waiting for a key to be pressed before displaying the menu. Unset by default. GRUB_DEFAULT_BUTTON GRUB_TIMEOUT_BUTTON GRUB_HIDDEN_TIMEOUT_BUTTON GRUB_BUTTON_CMOS_ADDRESS Variants of the corresponding variables without the _BUTTON sux, used to support vendor-specic power buttons. See Chapter 9 [Vendor power-on keys], page 39. GRUB_DISTRIBUTOR Set by distributors of GRUB to their identifying name. This is used to generate more informative menu entry titles. GRUB_TERMINAL_INPUT Select the terminal input device. You may select multiple devices here, separated by spaces. Valid terminal input names depend on the platform, but may include console (PC BIOS and EFI consoles), serial (serial terminal), ofconsole (Open Firmware console), at_keyboard (PC AT keyboard, mainly useful with Coreboot), or usb_keyboard (USB keyboard using the HID Boot Protocol, for cases where the rmware does not handle this). The default is to use the platforms native terminal input. GRUB_TERMINAL_OUTPUT Select the terminal output device. You may select multiple devices here, separated by spaces. Valid terminal output names depend on the platform, but may include console (PC BIOS and EFI consoles), serial (serial terminal), gfxterm
19
(graphics-mode output), ofconsole (Open Firmware console), or vga_text (VGA text output, mainly useful with Coreboot). The default is to use the platforms native terminal output. GRUB_TERMINAL If this option is set, it overrides both GRUB_TERMINAL_INPUT and GRUB_TERMINAL_OUTPUT to the same value. GRUB_SERIAL_COMMAND A command to congure the serial port when using the serial console. See Section 14.2.1 [serial], page 54. Defaults to serial. GRUB_CMDLINE_LINUX Command-line arguments to add to menu entries for the Linux kernel. GRUB_CMDLINE_LINUX_DEFAULT Unless GRUB_DISABLE_RECOVERY is set to true, two menu entries will be generated for each Linux kernel: one default entry and one entry for recovery mode. This option lists command-line arguments to add only to the default menu entry, after those listed in GRUB_CMDLINE_LINUX. GRUB_CMDLINE_NETBSD GRUB_CMDLINE_NETBSD_DEFAULT As GRUB_CMDLINE_LINUX and GRUB_CMDLINE_LINUX_DEFAULT, but for NetBSD. GRUB_CMDLINE_GNUMACH As GRUB_CMDLINE_LINUX, but for GNU Mach. GRUB_CMDLINE_XEN GRUB_CMDLINE_XEN_DEFAULT The values of these options are appended to the values of GRUB_CMDLINE_LINUX and GRUB_CMDLINE_LINUX_DEFAULT for Linux and Xen menu entries. GRUB_CMDLINE_LINUX_XEN_REPLACE GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT The values of these options replace the values of GRUB_CMDLINE_LINUX and GRUB_CMDLINE_LINUX_DEFAULT for Linux and Xen menu entries. GRUB_DISABLE_LINUX_UUID Normally, grub-mkconfig will generate menu entries that use universallyunique identiers (UUIDs) to identify the root lesystem to the Linux kernel, using a root=UUID=... kernel parameter. This is usually more reliable, but in some cases it may not be appropriate. To disable the use of UUIDs, set this option to true. GRUB_DISABLE_RECOVERY If this option is set to true, disable the generation of recovery mode menu entries. GRUB_VIDEO_BACKEND If graphical video support is required, either because the gfxterm graphical terminal is in use or because GRUB_GFXPAYLOAD_LINUX is set, then grubmkconfig will normally load all available GRUB video drivers and use the one
20
most appropriate for your hardware. If you need to override this for some reason, then you can set this option. After grub-install has been run, the available video drivers are listed in /boot/grub/video.lst. GRUB_GFXMODE Set the resolution used on the gfxterm graphical terminal. Note that you can only use modes which your graphics card supports via VESA BIOS Extensions (VBE), so for example native LCD panel resolutions may not be available. The default is auto, which tries to select a preferred resolution. See Section 13.1.8 [gfxmode], page 49. GRUB_BACKGROUND Set a background image for use with the gfxterm graphical terminal. The value of this option must be a le readable by GRUB at boot time, and it must end with .png, .tga, .jpg, or .jpeg. The image will be scaled if necessary to t the screen. GRUB_THEME Set a theme for use with the gfxterm graphical terminal. GRUB_GFXPAYLOAD_LINUX Set to text to force the Linux kernel to boot in normal text mode, keep to preserve the graphics mode set using GRUB_GFXMODE, width xheight [xdepth ] to set a particular graphics mode, or a sequence of these separated by commas or semicolons to try several modes in sequence. See Section 13.1.9 [gfxpayload], page 49. Depending on your kernel, your distribution, your graphics card, and the phase of the moon, note that using this option may cause GNU/Linux to suer from various display problems, particularly during the early part of the boot sequence. If you have problems, set this option to text and GRUB will tell Linux to boot in normal text mode. GRUB_DISABLE_OS_PROBER Normally, grub-mkconfig will try to use the external os-prober program, if installed, to discover other operating systems installed on the same system and generate appropriate menu entries for them. Set this option to true to disable this. GRUB_INIT_TUNE Play a tune on the speaker when GRUB starts. This is particularly useful for users unable to see the screen. The value of this option is passed directly to Section 14.3.35 [play], page 62. GRUB_BADRAM If this option is set, GRUB will issue a Section 14.3.2 [badram], page 55 command to lter out specied regions of RAM. GRUB_PRELOAD_MODULES This option may be set to a list of GRUB module names separated by spaces. Each module will be loaded as early as possible, at the start of grub.cfg.
21
For more detailed customisation of grub-mkconfigs output, you may edit the scripts in /etc/grub.d directly. /etc/grub.d/40_custom is particularly useful for adding entire custom menu entries; simply type the menu entries you want to add at the end of that le, making sure to leave at least the rst two lines intact.
Words
A word is a sequence of characters considered as a single unit by GRUB. Words are separated by metacharacters, which are the following plus space, tab, and newline: { } | & $ ; < > Quoting may be used to include metacharacters in words; see below.
Reserved words
Reserved words have a special meaning to GRUB. The following words are recognised as reserved when unquoted and either the rst word of a simple command or the third word of a for command: ! [[ ]] { } case do done elif else esac fi for function if in menuentry select then time until while Not all of these reserved words have a useful purpose yet; some are reserved for future expansion.
Quoting
Quoting is used to remove the special meaning of certain characters or words. It can be used to treat metacharacters as part of a word, to prevent reserved words from being recognised as such, and to prevent variable expansion. There are three quoting mechanisms: the escape character, single quotes, and double quotes. A non-quoted backslash (\) is the escape character. It preserves the literal value of the next character that follows, with the exception of newline. Enclosing characters in single quotes preserves the literal value of each character within the quotes. A single quote may not occur between single quotes, even when preceded by a backslash. Enclosing characters in double quotes preserves the literal value of all characters within the quotes, with the exception of $ and \. The $ character retains its special meaning within double quotes. The backslash retains its special meaning only when followed by one of the following characters: $, ", \, or newline. A backslash-newline pair is treated as a line continuation (that is, it is removed from the input stream and eectively
22
ignored1 ). A double quote may be quoted within double quotes by preceding it with a backslash.
Variable expansion
The $ character introduces variable expansion. The variable name to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from characters immediately following it which could be interpreted as part of the name. Normal variable names begin with an alphabetic character, followed by zero or more alphanumeric characters. These names refer to entries in the GRUB environment (see Chapter 13 [Environment], page 47). Positional variable names consist of one or more digits. They represent parameters passed to function calls, with $1 representing the rst parameter, and so on. The special variable name ? expands to the exit status of the most recently executed command. When positional variable names are active, other special variable names @, * and # are dened and they expand to all positional parameters with necessary quoting, positional parameters without any quoting, and positional parameter count respectively.
Comments
A word beginning with # causes that word and all remaining characters on that line to be ignored.
Simple commands
A simple command is a sequence of words separated by spaces or tabs and terminated by a semicolon or a newline. The rst word species the command to be executed. The remaining words are passed as arguments to the invoked command. The return value of a simple command is its exit status. If the reserved word ! precedes the command, then the return value is instead the logical negation of the commands exit status.
Compound commands
A compound command is one of the following: for name in word . . . ; do list; done The list of words following in is expanded, generating a list of items. The variable name is set to each element of this list in turn, and list is executed each time. The return value is the exit status of the last command that executes. If the expansion of the items following in results in an empty list, no commands are executed, and the return status is 0. if list; then list; [elif list; then list;] . . . [else list;] The if list is executed. If its exit status is zero, the then list is executed. Otherwise, each elif list is executed in turn, and if its exit status is zero, the
1
Currently a backslash-newline pair within a variable name is not handled properly, so use this feature with some care.
23
corresponding then list is executed and the command completes. Otherwise, the else list is executed, if present. The exit status is the exit status of the last command executed, or zero if no condition tested true. while cond ; do list; done until cond ; do list; done The while command continuously executes the do list as long as the last command in cond returns an exit status of zero. The until command is identical to the while command, except that the test is negated; the do list is executed as long as the last command in cond returns a non-zero exit status. The exit status of the while and until commands is the exit status of the last do list command executed, or zero if none was executed. function name { command ; . . . } This denes a function named name. The body of the function is the list of commands within braces, each of which must be terminated with a semicolon or a newline. This list of commands will be executed whenever name is specied as the name of a simple command. Function denitions do not aect the exit status in $?. When executed, the exit status of a function is the exit status of the last command executed in the body. menuentry title [--class=class . . . ] [--users=users] [--unrestricted] [--hotkey=key] { command ; . . . } See Section 14.1.1 [menuentry], page 53.
Built-in Commands
Some built-in commands are also provided by GRUB script to help script writers perform actions that are otherwise not possible. For example, these include commands to jump out of a loop without fully completing it, etc. break [n] Exit from within a for, while, or until loop. If n is specied, break n levels. n must be greater than or equal to 1. If n is greater than the number of enclosing loops, all enclosing loops are exited. The return value is 0 unless n is not greater than or equal to 1. Resume the next iteration of the enclosing for, while or until loop. If n is specied, resume at the nth enclosing loop. n must be greater than or equal to 1. If n is greater than the number of enclosing loops, the last enclosing loop (the top-level loop) is resumed. The return value is 0 unless n is not greater than or equal to 1. return [n] Causes a function to exit with the return value specied by n. If n is omitted, the return status is that of the last command executed in the function body. If used outside a function the return status is false. The positional parameters from n+1 . . . are renamed to $1 . . . . Parameters represented by the numbers $# down to $#-n+1 are unset. n must be a nonnegative number less than or equal to $#. If n is 0, no parameters are changed. If n is not given, it is assumed to be 1. If n is greater than $#, the positional
continue [n]
shift [n]
24
parameters are not changed. The return status is greater than zero if n is greater than $# or less than zero; otherwise 0.
25
insmod zfs search --set=root --label freepool --hint hd0,msdos7 kfreebsd /freebsd@/boot/kernel/kernel kfreebsd_module_elf /freebsd@/boot/kernel/opensolaris.ko kfreebsd_module_elf /freebsd@/boot/kernel/zfs.ko kfreebsd_module /freebsd@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd set kFreeBSD.hw.psm.synaptics_support=1 } menuentry "experimental GRUB" { search --set=root --label GRUB --hint hd0,msdos5 multiboot /experimental/grub/i386-pc/core.img } menuentry "Fedora 16 installer" { search --set=root --label GRUB --hint hd0,msdos5 linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280x800 initrd /fedora/initrd.img }
menuentry "Fedora rawhide installer" { search --set=root --label GRUB --hint hd0,msdos5 linux /fedora/vmlinuz repo=ftp://mirror.switch.ch/mirror/fedora/linux/develop initrd /fedora/initrd.img }
menuentry "Debian sid installer" { search --set=root --label GRUB --hint hd0,msdos5 linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd. } Notes: 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 root=hd0,msdosX but this is not recommened due to device name instability.
26
To embed a conguration le, use the -c option to grub-mkimage. The le is copied into the core image, so it may reside anywhere on the le system, and may be removed after running grub-mkimage. After the embedded conguration le (if any) is executed, GRUB will load the normal module (see Section 14.3.30 [normal], page 61), which will then read the real conguration le from $prefix/grub.cfg. By this point, the root variable will also have been set to the root device name. For example, prefix might be set to (hd0,1)/boot/grub, and root might be set to hd0,1. Thus, in most cases, the embedded conguration le only needs to set the prefix and root variables, and then drop through to GRUBs normal processing. A typical example of this might look like this: search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root set prefix=($root)/boot/grub (The search_fs_uuid module must be included in the core image for this example to work.) In more complex cases, it may be useful to read other conguration les directly from the embedded conguration le. This allows such things as reading les not called grub.cfg, or reading les from a directory other than that where GRUBs loadable modules are installed. To do this, include the configfile and normal modules in the core image, and embed a conguration le that uses the configfile command to load another le. The following example of this also requires the echo, search_label, and test modules to be included in the core image: search.fs_label grub root if [ -e /boot/grub/example/test1.cfg ]; then set prefix=($root)/boot/grub configfile /boot/grub/example/test1.cfg else if [ -e /boot/grub/example/test2.cfg ]; then set prefix=($root)/boot/grub configfile /boot/grub/example/test2.cfg else echo "Could not find an example configuration file!" fi fi The embedded conguration le may not contain menu entries directly, but may only read them from elsewhere using configfile.
27
6 Theme le format
6.1 Introduction
The GRUB graphical menu supports themes that can customize the layout and appearance of the GRUB boot menu. The theme is congured through a plain text le that species the layout of the various GUI components (including the boot menu, timeout progress bar, and text messages) as well as the appearance using colors, fonts, and images. Example is available in docs/example theme.txt
6.2.2 Fonts
The fonts GRUB uses PFF2 font format bitmap fonts. Fonts are specied with full font names. Currently there is no provision for a preference list of fonts, or deriving one font from another. Fonts are loaded with the loadfont command in GRUB. To see the list of loaded fonts, execute the lsfonts command. If there are too many fonts to t on screen, do set pager=1 before executing lsfonts.
28
remaining. For the circular progress indicator, there are two images used to render it: the *center* image, and the *tick* image. The center image is rendered in the center of the component, while the tick image is used to render each mark along the circumference of the indicator.
6.2.5 Labels
Text labels can be placed on the boot screen. The font, color, and horizontal alignment can be specied for labels. If a label is given the id timeout , then the text property for that label is also updated with a message informing the user of the number of seconds remaining until automatic boot. This is useful in case you want the text displayed somewhere else instead of directly on the progress bar.
To support any size of box on screen, the center slice and the slices for the top, bottom, and sides are all scaled to the correct size for the component on screen, using the following rules: 1. 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. 2. The corner slices (northwest, northeast, southeast, and southwest) are not scaled. 3. The center slice is scaled to ll the remaining space in the middle. As an example of how an image might be sliced up, consider the styled box used for a terminal view. Figure 6.3
29
2. Create a new layer on the top of the layer stack. Make it visible. Select this layer as the 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 of the slices must meet precisely; if it is o 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. 4. 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. 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 for 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 will create PNG les in the same directory as the drawing, named after the slices. These can now be used for a styled box in a GRUB theme.
30
Denes the font used for the title message at the top of the screen. Denes the color of the title message. Denes the font used for messages, such as when GRUB is unable to automatically boot an entry. Denes the color of the message text. Denes the background color of the message text area. Species the image to use as the background. It will be scaled to t the screen size. Species the color for the background if *desktopimage* is not specied. Species the le name pattern for the styled box slices used for the command line terminal window. For example, terminal-box: terminal *.png will use the images terminal c.png as the center area, terminal n.png as the north (top) edge, terminal nw.png as the northwest (upper left) corner, and so on. If the image for any slice is not found, it will simply be left empty.
31
image A component that displays an image. The image is scaled to t the component, although the preferred size defaults to the images original size unless the preferred size property is explicitly set. Properties: le The full path to the image le to load. progress bar Displays a horizontally oriented progress bar. It can be rendered using simple solid lled rectangles, or using a pair of pixmap styled boxes. Properties: fg color bg color border color text color show text The foreground color for plain solid color rendering. The background color for plain solid color rendering. The border color for plain solid color rendering. The text color. Boolean value indicating whether or not text should be displayed on the progress bar. If set to *false*, then no text will be displayed on the bar. If set to any other value, text will be displayed on the bar. The styled box specication for the frame of the progress bar. Example: progress frame *.png The styled box specication for the highlighted region of the progress bar. This box will be used to paint just the highlighted region of the bar, and will be increased in size as the bar nears completion. Example: progress hl *.png. The text to display on the progress bar. If the progress bars ID is set to timeout , then GRUB will updated this property with an informative message as the timeout approaches. The progress bar current value. Normally not set manually. The progress bar start value. Normally not set manually. The progress bar end value. Normally not set manually.
text
circular progress Displays a circular progress indicator. The appearance of this component is determined by two images: the *center* image and the *tick* image. The center image is generally larger and will be drawn in the center of the component. Around the circumference of a circle within the component, the tick image will be drawn a certain number of times, depending on the properties of the component. Properties: center bitmap tick bitmap num ticks ticks disappear The le name of the image to draw in the center of the component. The le name of the image to draw for the tick marks. The number of ticks that make up a full circle. Boolean value indicating whether tick marks should progressively appear, or progressively disappear as *value* approaches *end*. Specify true or false. The progress indicator current value. Normally not set manually.
value
32
start end
The progress indicator start value. Normally not set manually. The progress indicator end value. Normally not set manually.
boot menu Displays the GRUB boot menu. It allows selecting items and executing them. Properties: item font selected item font The font to use for the menu item titles. The font to use for the selected menu item, or inherit (the default) to use item font for the selected menu item as well. The color to use for the menu item titles. The color to use for the selected menu item, or inherit (the default) to use item color for the selected menu item as well. The width of menu item icons. Icons are scaled to the specied size. The height of menu item icons. The height of each menu item in pixels. The amount of space in pixels to leave on each side of the menu item contents. The space between an items icon and the title text, in pixels. The amount of space to leave between menu items, in pixels. The image le pattern for the menu frame styled box. Example: menu *.png (this will use images such as menu c.png, menu w.png, menu nw.png, etc.) The image le pattern for the selected item highlight styled box. Boolean value indicating whether the scroll bar should be drawn if the frame and thumb styled boxes are congured. The image le pattern for the entire scroll bar. Example: scrollbar *.png The image le pattern for the scroll bar thumb (the part of the scroll bar that moves as scrolling occurs). Example: scrollbar thumb *.png The maximum number of items to show on the menu. If there are more than *max items shown* items in the menu, the list will scroll to make all items accessible.
icon width icon height item height item padding item icon space item spacing menu pixmap style
33
canvas Canvas is a container that allows manual placement of components within it. It does not alter the positions of its child components. It assigns all child components their preferred sizes. hbox The *hbox* container lays out its children from left to right, giving each one its preferred width. The height of each child is set to the maximum of the preferred heights of all children. vbox The *vbox* container lays out its children from top to bottom, giving each one its preferred height. The width of each child is set to the maximum of the preferred widths of all children.
35
The following instructions only work on PC BIOS systems where the Preboot eXecution Environment (PXE) is available. To generate a PXE boot image, run: grub-mkimage --format=i386-pc-pxe --output=grub.pxe --prefix=(pxe)/boot/grub pxe pxec 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 from the TFTP server root. Set the DHCP server conguration to oer grub.pxe as the boot le (the filename option in ISC dhcpd). You can also use the grub-mknetdir utility to generate an image and a GRUB directory tree, rather than copying les around manually. After 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) device name to (pxe:server-ip ) or (pxe:server-ip :gateway-ip ). Note that this should be changed both in the prex and in any references to the device name in the conguration le. GRUB provides several environment variables which may be used to inspect or change the behaviour of the PXE device: net_pxe_ip The IP address of this machine. Read-only. net_pxe_mac The network interfaces MAC address. Read-only. net_pxe_hostname The client host name provided by DHCP. Read-only. net_pxe_domain The client domain name provided by DHCP. Read-only. net_pxe_rootpath The path to the clients root disk provided by DHCP. Read-only. net_pxe_extensionspath The path to additional DHCP vendor extensions provided by DHCP. Read-only. net_pxe_boot_file The boot le name provided by DHCP. Read-only. net_pxe_dhcp_server_name The name of the DHCP server responsible for these boot parameters. Readonly. net_default_server The default server. Read-write, although setting this is only useful before opening a network device.
37
39
41
42
*.mod
Everything else in GRUB resides in dynamically loadable modules. These are often loaded automatically, or built into the core image if they are essential, but may also be loaded manually using the insmod command (see Section 14.3.22 [insmod], page 59).
*_stage1_5 In GRUB Legacy, Stage 1.5s function was to include enough lesystem code to allow the much larger Stage 2 to be read from an ordinary lesystem. In this respect, its function was similar to core.img in GRUB 2. However, core.img is much more capable than Stage 1.5 was; since it oers a rescue shell, it is sometimes possible to recover manually in the event that it is unable to load any other modules, for example if partition numbers have changed. core.img is built in a more exible way, allowing GRUB 2 to support reading modules from advanced disk types such as LVM and RAID. GRUB Legacy could run with only Stage 1 and Stage 2 in some limited congurations, while GRUB 2 requires core.img and cannot work without it. stage2 GRUB 2 has no single Stage 2 image. /boot/grub at run-time. Instead, it loads modules from
stage2_eltorito In GRUB 2, images for booting from CD-ROM drives are now constructed using cdboot.img and core.img, making sure that the core image contains the iso9660 module. It is usually best to use the grub-mkrescue program for this. nbgrub pxegrub There is as yet no equivalent for nbgrub in GRUB 2; it was used by Etherboot and some other network boot loaders. In GRUB 2, images for PXE network booting are now constructed using pxeboot.img and core.img, making sure that the core image contains the pxe and pxecmd modules. See Chapter 7 [Network], page 35.
43
44
(hd0,msdos1) (hd0,msdos1,msdos5) (hd0,msdos1,bsd3) (hd0,netbsd1) (hd0,gpt1) (hd0,1,3) If you enabled the network support, the special drives (tftp), (http) and so on ars also available. Before using the network drive, you must initialize the network. See Chapter 7 [Network], page 35, for more information. If you boot GRUB from a CD-ROM, (cd) is available. See Section 3.2 [Making a GRUB bootable CD-ROM], page 10, for details.
45
C-P PC UP KEY Move up through the history list. C-N PC DOWN KEY Move down through the history list.
1
However, this behavior will be changed in the future version, in a user-invisible way.
46
When typing commands interactively, if the cursor is within or before the rst word in the command-line, pressing the TAB key (or C-I) will display a listing of the available commands, and if the cursor is after the rst word, the TAB will provide a completion listing of disks, partitions, and le names depending on the context. Note that to obtain a list of drives, one must open a parenthesis, as root (. Note that you cannot use the completion functionality in the TFTP lesystem. This is because TFTP doesnt support le name listing for the security.
47
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 (see Section 13.1.29 [root], page 51) so that it can set up registers properly. If the biosnum variable is set, it overrides GRUBs own means of guessing this. For an alternative approach which also changes BIOS drive mappings for the chainloaded system, see Section 14.3.12 [drivemap], page 57.
13.1.2 chosen
When executing a menu entry, GRUB sets the chosen variable to the title of the entry being executed. If the menu entry is in one or more submenus, then chosen is set to the titles of each of the submenus starting from the top level followed by the title of the menu entry itself, separated by >.
48
magenta brown light-gray dark-gray light-blue light-green light-cyan light-red light-magenta yellow white The default is white/black.
13.1.5 debug
This variable may be set to enable debugging output from various components of GRUB. The value is a list of debug facility names separated by whitespace or ,, or all to enable all available debugging output.
13.1.6 default
If this variable is set, it identies a menu entry that should be selected by default, possibly after a timeout (see Section 13.1.32 [timeout], page 51). The entry may be identied by number or by title. If the entry is in a submenu, then it must be identied using the titles of each of the submenus starting from the top level followed by the number or title of the menu entry itself, separated by >. For example, take the following 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 often set by GRUB_DEFAULT (see Section 5.1 [Simple conguration], page 17), grub-set-default, or grub-reboot.
13.1.7 fallback
If this variable is set, it identies a menu entry that should be selected if the default menu entry fails to boot. Entries are identied in the same way as for default (see Section 13.1.6 [default], page 48).
49
13.1.8 gfxmode
If this variable is set, it sets the resolution used on the gfxterm graphical terminal. Note that you can only use modes which your graphics card supports via VESA BIOS Extensions (VBE), so for example native LCD panel resolutions may not be available. The default is auto, which selects a platform-specic default that should look reasonable. The resolution may be specied as a sequence of one or more modes, separated by commas (,) or semicolons (;); each will be tried in turn until one is found. Each mode should be either auto, width xheight , or width xheight xdepth .
13.1.9 gfxpayload
If this variable is set, it controls the video mode in which the Linux kernel starts up, replacing the vga= boot option (see Section 14.3.24 [linux], page 60). It may be set to text to force the Linux kernel to boot in normal text mode, keep to preserve the graphics mode set using gfxmode, or any of the permitted values for gfxmode to set a particular graphics mode (see Section 13.1.8 [gfxmode], page 49). Depending on your kernel, your distribution, your graphics card, and the phase of the moon, note that using this option may cause GNU/Linux to suer from various display problems, particularly during the early part of the boot sequence. If you have problems, set this variable to text and GRUB will tell Linux to boot in normal text mode. The default is platform-specic. On platforms with a native text mode (such as PC BIOS platforms), the default is text. Otherwise the default may be auto or a specic video mode. This variable is often set by GRUB_GFXPAYLOAD_LINUX (see Section 5.1 [Simple conguration], page 17).
13.1.11 icondir
If this variable is set, it names a directory in which the GRUB graphical menu should look for icons after looking in the themes icons directory. See Chapter 6 [Theme le format], page 27.
13.1.12 lang
If this variable is set, it names the language code that the gettext command (see Section 14.3.16 [gettext], page 58) uses to translate strings. For example, French would be named as fr, and Simplied Chinese as zh_CN. grub-mkconfig (see Section 5.1 [Simple conguration], page 17) will try to set a reasonable default for this variable based on the system locale.
50
grub-mkconfig (see Section 5.1 [Simple conguration], page 17) will set a reasonable default for this variable if internationalization is needed and any translation les are available.
13.1.24 pager
If set to 1, pause output after each screenful and wait for keyboard input. The default is not to pause output.
51
13.1.25 prex
The location of the /boot/grub directory as an absolute le name (see Section 11.2 [File name syntax], page 44). This is normally set by GRUB at startup based on information provided by grub-install. GRUB modules are dynamically loaded from this directory, so it must be set correctly in order for many parts of GRUB to work.
13.1.29 root
The root device name (see Section 11.1 [Device syntax], page 43). Any le names that do not specify an explicit device name are read from this device. The default is normally set by GRUB at startup based on the value of prefix (see Section 13.1.25 [prex], page 51). For example, if GRUB was installed to the rst partition of the rst hard disk, then prefix 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 of superuser names to enable authentication support. See Chapter 22 [Security], page 81.
13.1.31 theme
This variable may be set to a directory containing a GRUB graphical menu theme. See Chapter 6 [Theme le format], page 27. This variable is often set by GRUB_THEME (see Section 5.1 [Simple conguration], page 17).
13.1.32 timeout
If this variable is set, it species the time in seconds to wait for keyboard input before booting the default menu entry. A timeout of 0 means to boot the default entry immediately without displaying the menu; a timeout of -1 (or unset) means to wait indenitely. This variable is often set by GRUB_TIMEOUT or GRUB_HIDDEN_TIMEOUT (see Section 5.1 [Simple conguration], page 17).
52
a GRUB conguration le cannot just create a le in the ordinary way. However, GRUB provides an environment block which can be used to save a small amount of 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, the load_ env command (see Section 14.3.27 [load env], page 60) loads environment variables from it, and the save_env (see Section 14.3.39 [save env], page 63) command saves environment variables to it. From a running system, the grub-editenv utility can be used to edit the environment block. For safety reasons, this storage is only available when installed on a plain disk (no LVM or RAID), using a non-checksumming lesystem (no ZFS), and using BIOS or EFI functions (no ATA, USB or IEEE1275). grub-mkconfig uses this facility to implement GRUB_SAVEDEFAULT (see Section 5.1 [Simple conguration], page 17).
53
14.1.1 menuentry
menuentry title [--class=class . . . ] [--users=users] [--unrestricted] [--hotkey=key] { command ; . . . }
[Command]
This denes a GRUB menu entry named title. When this entry is selected from the menu, GRUB will set the chosen environment variable to title, execute the list of commands given within braces, and if the last command in the list returned successfully and a kernel was loaded it will execute the boot command. The --class option may be used any number of times to group menu entries into classes. Menu themes may display dierent classes using dierent styles. The --users option grants specic users access to specic menu entries. See Chapter 22 [Security], page 81. The --unrestricted option grants all users access to specic menu entries. See Chapter 22 [Security], page 81. The --hotkey option associates a hotkey with a menu entry. key may be a single letter, or one of the aliases backspace, tab, or delete.
14.1.2 submenu
submenu title [--class=class . . . ] [--users=users] [--unrestricted] [--hotkey=key] { menu entries . . . }
[Command]
This denes a submenu. An entry called title will be added to the menu; when that entry is selected, a new menu will be displayed showing all the entries within this submenu.
54
All options are the same as in the menuentry command (see Section 14.1.1 [menuentry], page 53).
14.2.1 serial
serial [--unit=unit] [--port=port] [--speed=speed] [--word=word] [--parity=parity] [--stop=stop]
[Command]
Initialize a serial device. unit is a number in the range 0-3 specifying which serial port to use; default is 0, which corresponds to the port often called COM1. port is the I/O port where the UART is to be found; if specied it takes precedence over unit. speed is the transmission speed; default is 9600. word and stop are the number of data bits and stop bits. Data bits must be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data bits and one stop bit. parity is one of no, odd, even and defaults 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 54, see Section 14.2.3 [terminal output], page 54). See also Chapter 8 [Serial terminal], page 37.
55
14.2.4 terminfo
terminfo [-a|-u|-v] [term]
[Command] Dene the capabilities of your terminal by giving the name of an entry in the terminfo database, which should correspond roughly to a TERM environment variable in Unix. The currently available terminal types are vt100, vt100-color, ieee1275, and dumb. If you need other terminal types, please contact us to discuss the best way to include support for these in GRUB. The -a (--ascii), -u (--utf8), and -v (--visual-utf8) options control how non-ASCII text is displayed. -a species an ASCII-only terminal; -u species logically-ordered UTF-8; and -v species "visually-ordered UTF-8" (in other words, arranged such that a terminal emulator without bidirectional text support will display right-to-left text in the proper order; this is not really proper UTF-8, but a workaround). If no option or terminal type is specied, the current terminal type is printed.
14.3.1 acpi
acpi [-1|-2] [Command] [--exclude=table1,...|--load-only=table1,...] [--oemid=id] [--oemtable=table] [--oemtablerev=rev] [--oemtablecreator=creator] [--oemtablecreatorrev=rev] [--no-ebda] lename . . .
Modern BIOS systems normally implement the Advanced Conguration and Power Interface (ACPI), and dene various tables that describe the interface between an ACPI-compliant operating system and the rmware. In some cases, the tables provided by default only work well with certain operating systems, and it may be necessary to replace some of them. Normally, this command will replace the Root System Description Pointer (RSDP) in the Extended BIOS Data Area to point to the new tables. If the --no-ebda option is used, the new tables will be known only to GRUB, but may be used by GRUBs EFI emulation.
14.3.2 badram
badram addr,mask[,addr,mask...]
Filter out bad RAM. This command noties the memory manager that specied regions of RAM ought to be ltered out (usually, because theyre damaged). This remains in eect after a payload kernel has been loaded by GRUB, as long as the loaded kernel obtains its memory map from GRUB. Kernels that support this include Linux, GNU Mach, the kernel of FreeBSD and Multiboot kernels in general. [Command]
56
Syntax is the same as provided by the Memtest86+ utility: a list of address/mask pairs. Given a page-aligned address and a base address / mask pair, if all the bits of the page-aligned address that are enabled by the mask match with the base address, it means this page is to be ltered. This syntax makes it easy to represent patterns that are often result of memory damage, due to physical distribution of memory cells.
14.3.3 blocklist
blocklist le
Print a block list (see Section 11.3 [Block list syntax], page 44) for le. [Command]
14.3.4 boot
boot
[Command] Boot the OS or chain-loader which has been loaded. Only necessary if running the fully interactive command-line (it is implicit at the end of a menu entry).
14.3.5 cat
cat [--dos] le
[Command] Display the contents of the le le. This command may be useful to remind you of your OSs root partition: grub> cat /etc/fstab If the --dos option is used, then carriage return / new line pairs will be displayed as a simple new line. Otherwise, the carriage return will be displayed as a control character (<d>) to make it easier to see when boot problems are caused by a le formatted using DOS-style line endings.
14.3.6 chainloader
chainloader [--force] le
[Command] Load le 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 44) to grab the rst sector of the current partition with +1. If you specify the option --force, then load le forcibly, whether it has a correct signature or not. This is required when you want to load a defective boot loader, such as SCO UnixWare 7.1.
14.3.7 cmp
cmp le1 le2
[Command] Compare the le le1 with the le le2. If they dier in size, print the sizes like this: Differ in size: 0x1234 [foo], 0x4321 [bar] If the sizes are equal but the bytes at an oset dier, then print the bytes like this: Differ at the offset 777: 0xbe [foo], 0xef [bar] If they are completely identical, nothing will be printed.
57
14.3.8 congle
configfile le
[Command] Load le as a conguration le. If le denes any menu entries, then show a menu containing them immediately.
14.3.9 cpuid
cpuid [-l]
[Command] Check for CPU features. This command is only available on x86 systems. With the -l option, return true if the CPU supports long mode (64-bit). If invoked without options, this command currently behaves as if it had been invoked with -l. This may change in the future.
14.3.10 crc
crc le
Display the CRC32 checksum of le. [Command]
14.3.11 date
date [[year-]month-day] [hour:minute[:second]]
[Command] With no arguments, print the current date and time. Otherwise, take the current date and time, change any elements specied as arguments, and set the result as the new date and time. For example, date 01-01 will set the current month and day to January 1, but leave the year, hour, minute, and second unchanged.
14.3.12 drivemap
drivemap -l|-r|[-s] from drive to drive
[Command] Without options, map the drive from drive to the drive to drive. This is necessary when you chain-load some operating systems, such as DOS, if such an OS resides at a non-rst drive. For convenience, any partition sux on the drive is ignored, so you can safely use ${root} as a drive specication. With the -s option, perform the reverse mapping as well, swapping the two drives. With the -l option, list the current mappings. With the -r option, reset all mappings to the default values. For example: drivemap -s (hd0) (hd1)
14.3.13 echo
echo [-n] [-e] string . . .
[Command] Display the requested text and, unless the -n option is used, a trailing new line. If there is more than one string, they are separated by spaces in the output. As usual in GRUB commands, variables may be substituted using ${var}.
58
The -e option enables interpretation of backslash escapes. The following sequences are recognised: \\ \a \c \f \n \r \t \v backslash alert (BEL) suppress trailing new line form feed new line carriage return horizontal tab vertical tab
When interpreting backslash escapes, backslash followed by any other character will print that character.
14.3.14 export
export envvar
[Command] Export the environment variable envvar. Exported variables are visible to subsidiary conguration les loaded using configfile.
14.3.15 false
false
[Command] Do nothing, unsuccessfully. This is mainly useful in control constructs such as if and while (see Section 5.2 [Shell-like scripting], page 21).
14.3.16 gettext
gettext string
Translate 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 49). Translation les in MO format are read from locale_dir (see Section 13.1.13 [locale dir], page 49), usually /boot/grub/locale. [Command]
14.3.17 gptsync
gptsync device [partition[+/-[type]]] . . .
[Command] Disks using the GUID Partition Table (GPT) also have a legacy Master Boot Record (MBR) partition table for compatibility with the BIOS and with older operating systems. The legacy MBR can only represent a limited subset of GPT partition entries. This command populates the legacy MBR with the specied partition entries on device. Up to three partitions may be used.
59
type is an MBR partition type code; prex with 0x if you want to enter this in hexadecimal. The separator between partition and type may be + to make the partition active, or - to make it inactive; only one partition may be active. If both the separator and type are omitted, then the partition will be inactive.
14.3.18 halt
halt --no-apm
[Command] The command halts the computer. If the --no-apm option is specied, no APM BIOS call is performed. Otherwise, the computer is shut down using APM.
14.3.19 help
help [pattern . . . ]
[Command] Display helpful information about builtin commands. If you do not specify pattern, this command shows short descriptions of all available commands. If you specify any patterns, it displays longer information about each of the commands whose names begin with those patterns.
14.3.20 initrd
initrd le
[Command] Load an initial ramdisk for a Linux kernel image, and set the appropriate parameters in the Linux setup area in memory. This may only be used after the linux command (see Section 14.3.24 [linux], page 60) has been run. See also Section 4.3.2 [GNU/Linux], page 14.
14.3.21 initrd16
initrd16 le
[Command] Load an initial ramdisk for a Linux kernel image to be booted in 16-bit mode, and set the appropriate parameters in the Linux setup area in memory. This may only be used after the linux16 command (see Section 14.3.25 [linux16], page 60) has been run. See also Section 4.3.2 [GNU/Linux], page 14. This command is only available on x86 systems.
14.3.22 insmod
insmod module
Insert the dynamic GRUB module called module. [Command]
14.3.23 keystatus
keystatus [--shift] [--ctrl] [--alt]
[Command] Return true if the Shift, Control, or Alt modier keys are held down, as requested by options. This is useful in scripting, to allow some user control over behaviour without having to wait for a keypress. Checking key modier status is only supported on some platforms. If invoked without any options, the keystatus command returns true if and only if checking key modier status is supported.
60
14.3.24 linux
linux le . . .
[Command] Load a Linux kernel image from le. The rest of the line is passed verbatim as the kernel command-line. Any initrd must be reloaded after using this command (see Section 14.3.20 [initrd], page 59). On x86 systems, the kernel will be booted using the 32-bit boot protocol. Note that this means that the vga= boot option will not work; if you want to set a special video mode, you will need to use GRUB commands such as set gfxpayload=1024x768 or set gfxpayload=keep (to keep the same mode as used in GRUB) instead. GRUB can automatically detect some uses of vga= and translate them to appropriate settings of gfxpayload. The linux16 command (see Section 14.3.25 [linux16], page 60) avoids this restriction.
14.3.25 linux16
linux16 le . . .
[Command] Load a Linux kernel image from le in 16-bit mode. The rest of the line is passed verbatim as the kernel command-line. Any initrd must be reloaded after using this command (see Section 14.3.21 [initrd16], page 59). The kernel will be booted using the traditional 16-bit boot protocol. As well as bypassing problems with vga= described in Section 14.3.24 [linux], page 60, this permits booting some other programs that implement the Linux boot protocol for the sake of convenience. This command is only available on x86 systems.
14.3.28 loopback
loopback [-d] device le
[Command] Make the device named device correspond to the contents of the lesystem image in le. For example: loopback loop0 /path/to/image ls (loop0)/ With the -d option, delete a device previously created using this command.
61
14.3.29 ls
ls [arg . . . ]
List devices or les. With no arguments, print all devices known to GRUB. If the argument is a device name enclosed in parentheses (see Section 11.1 [Device syntax], page 43), then list all les at the root directory of that device. If the argument is a directory given as an absolute le name (see Section 11.2 [File name syntax], page 44), then list the contents of that directory. [Command]
14.3.30 normal
normal [le]
Enter normal mode and display the GRUB menu. In normal mode, commands, lesystem modules, and cryptography modules are automatically loaded, and the full GRUB script parser is available. Other modules may be explicitly loaded using insmod (see Section 14.3.22 [insmod], page 59). If a le is given, then commands will be read from that le. Otherwise, they will be read from $prefix/grub.cfg if it exists. normal may be called from within normal mode, creating a nested environment. It is more usual to use configfile (see Section 14.3.8 [congle], page 57) for this. [Command]
14.3.32 parttool
parttool partition commands
Make various modications to partition table entries. Each command is either a boolean option, in which case it must be followed with + or - (with no intervening space) to enable or disable that option, or else it takes a value in the form command =value . Currently, parttool is only useful on DOS partition tables (also known as Master Boot Record, or MBR). On these partition tables, the following commands are available: boot (boolean) When enabled, this makes the selected partition be the active (bootable) partition on its disk, clearing the active ag on all other partitions. This command is limited to primary partitions. type (value) Change the type of an existing partition. The value must be a number in the range 0-0xFF (prex with 0x to enter it in hexadecimal). [Command]
62
hidden (boolean) When enabled, this hides the selected partition by setting the hidden bit in its partition type code; when disabled, unhides the selected partition by clearing this bit. This is useful only when booting DOS or Wwindows and multiple primary FAT partitions exist in one disk. See also Section 4.3.3 [DOS/Windows], page 15.
14.3.33 password
password user clear-password
[Command] Dene a user named user with password clear-password. See Chapter 22 [Security], page 81.
14.3.35 play
play le | tempo [pitch1 duration1] [pitch2 duration2] ...
[Command] Plays a tune If the argument is a le name (see Section 11.2 [File name syntax], page 44), play the tune recorded in it. The le format is rst the tempo as an unsigned 32bit little-endian number, then pairs of unsigned 16bit little-endian numbers for pitch and duration pairs. If the arguments are a series of numbers, play the inline tune. The tempo is the base for all note durations. 60 gives a 1-second base, 120 gives a half-second base, etc. Pitches are Hz. Set pitch to 0 to produce a rest.
14.3.37 read
read [var]
[Command] Read a line of input from the user. If an environment variable var is given, set that environment variable to the line of input that was read, with no terminating newline.
14.3.38 reboot
reboot
Reboot the computer. [Command]
63
14.3.40 search
search [--file|--label|--fs-uuid] [--set [var]] [--no-floppy] name
[Command]
Search devices by le (-f, --file), lesystem label (-l, --label), or lesystem UUID (-u, --fs-uuid). If the --set option is used, the rst device found is set as the value of environment variable var. The default variable is root. The --no-floppy option prevents searching oppy devices, which can be slow. The search.file, search.fs_label, and search.fs_uuid commands are aliases for search --file, search --label, and search --fs-uuid respectively.
14.3.41 sendkey
sendkey [--num|--caps|--scroll|--insert| [Command] --pause|--left-shift|--right-shift| --sysrq|--numkey|--capskey|--scrollkey| --insertkey|--left-alt|--right-alt| --left-ctrl|--right-ctrl on|off] . . . [no-led] keystroke
Insert keystrokes into the keyboard buer when booting. Sometimes an operating system or chainloaded boot loader requires particular keys to be pressed: for example, one might need to press a particular key to enter "safe mode", or when chainloading another boot loader one might send keystrokes to it to navigate its menu. You may provide up to 16 keystrokes (the length of the BIOS keyboard buer). Keystroke names may be upper-case or lower-case letters, digits, or taken from the following table: Name escape exclam at numbersign dollar percent caret ampersand asterisk parenleft parenright minus Key Escape ! @ # $ % ^ & * ( ) -
64
underscore equal plus backspace tab bracketleft braceleft bracketright braceright enter control semicolon colon quote doublequote backquote tilde shift backslash bar comma less period greater slash question rshift alt space capslock F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 num1 num2 num3 num4 num5
= + Backspace Tab [ { ] } Enter press and release Control ; : " ~ press and release left Shift \ | , < . > / ? press and release right Shift press and release Alt space bar Caps Lock F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 1 (numeric keypad) 2 (numeric keypad) 3 (numeric keypad) 4 (numeric keypad) 5 (numeric keypad)
65
num6 num7 num8 num9 num0 numperiod numend numdown numpgdown numleft numcenter numright numhome numup numpgup numinsert numdelete numasterisk numminus numplus numslash numenter delete insert home end pgdown pgup down up left right
6 (numeric keypad) 7 (numeric keypad) 8 (numeric keypad) 9 (numeric keypad) 0 (numeric keypad) . (numeric keypad) End (numeric keypad) Down (numeric keypad) Page Down (numeric keypad) Left (numeric keypad) 5 with Num Lock inactive (numeric keypad) Right (numeric keypad) Home (numeric keypad) Up (numeric keypad) Page Up (numeric keypad) Insert (numeric keypad) Delete (numeric keypad) * (numeric keypad) - (numeric keypad) + (numeric keypad) / (numeric keypad) Enter (numeric keypad) Delete Insert Home End Page Down Page Up Down Up Left Right
As well as keystrokes, the sendkey command takes various options that aect the BIOS keyboard status ags. These options take an on or off parameter, specifying that the corresponding status ag be set or unset; omitting the option for a given status ag will leave that ag at its initial state at boot. The --num, --caps, --scroll, and --insert options emulate setting the corresponding mode, while the --numkey, --capskey, --scrollkey, and --insertkey options emulate pressing and holding the corresponding key. The other status ag options are selfexplanatory. If the --no-led option is given, the status ag options will have no eect on keyboard LEDs. If the sendkey command is given multiple times, then only the last invocation has any eect.
66
Since sendkey manipulates the BIOS keyboard buer, it may cause hangs, reboots, or other misbehaviour on some systems. If the operating system or boot loader that runs after GRUB uses its own keyboard driver rather than the BIOS keyboard functions, then sendkey will have no eect. This command is only available on PC BIOS systems.
14.3.42 set
set [envvar=value]
[Command] Set the environment variable envvar to value. If invoked with no arguments, print all environment variables with their values.
14.3.43 true
true
[Command] Do nothing, successfully. This is mainly useful in control constructs such as if and while (see Section 5.2 [Shell-like scripting], page 21).
14.3.44 unset
unset envvar
Unset the environment variable envvar. [Command]
14.3.45 uppermem
This command is not yet implemented for GRUB 2, although it is planned.
67
15 Charset
GRUB uses UTF-8 internally other than in rendering where some GRUB-specic appropriate representation is used. All text les (including cong) are assumed to be encoded in UTF-8.
69
16 Filesystems
NTFS, JFS, UDF, HFS+, exFAT, long lenames in FAT, Joliet part of ISO9660 are treated as UTF-16 as per specication. AFS and BFS are read as UTF-8, again according to specication. BtrFS, cpio, tar, squash4, minix, minix2, minix3, ROMFS, ReiserFS, XFS, ext2, ext3, ext4, FAT (short names), RockRidge part of ISO9660, nilfs2, UFS1, UFS2 and ZFS are assumed to be UTF-8. This might be false on systems congured with legacy charset but as long as the charset used is superset of ASCII you should be able to access ASCIInamed les. And its recommended to congure your system to use UTF-8 to access the lesystem, convmv may help with migration. ISO9660 (plain) lenames are specied as being ASCII or being described with unspecied escape sequences. GRUB assumes that the ISO9660 names are UTF-8 (since any ASCII is valid UTF-8). There are some old CDROMs which use CP437 in non-compliant way. Youre still able to access les with names containing only ASCII characters on such lesystems though. Youre also able to access any le if the lesystem contains valid Joliet (UTF-16) or RockRidge (UTF-8). AFFS, SFS and HFS never use unicode and GRUB assumes them to be in Latin1, Latin1 and MacRoman respectively. GRUB handles lesystem case-insensitivity however no attempt is performed at case conversion of international characters so e.g. a le named lowercase greek alpha is treated as dierent from the one named as uppercase alpha. The lesystems in questions are NTFS (except POSIX namespace), HFS+ (congurable at mkfs time, default insensitive), SFS (congurable at mkfs time, default insensitive), JFS (congurable at mkfs time, default sensitive), HFS, AFFS, FAT, exFAT and ZFS (congurable on per-subvolume basis by property casesensitivity, default sensitive). On ZFS subvolumes marked as case insensitive les containing lowercase international characters are inaccessible. Also like all supported lesystems except HFS+ and ZFS (congurable on per-subvolume basis by property normalization, default none) GRUB makes no attempt at check of canonical equivalence so a le name u-diaresis is treated as distinct from u+combining diaresis. This however means that in order to access le on HFS+ its name must be specied in normalisation form D. On normalized ZFS subvolumes lenames out of normalisation are inaccessible.
71
17 Output terminal
Firmware output console console on ARC and IEEE1275 are limited to ASCII. BIOS rmware console and VGA text are limited to ASCII and some pseudographics. None of above mentioned is appropriate for displaying international and any unsupported character is replaced with question mark except pseudographics which we attempt to approximate with ASCII. EFI console on the other hand nominally supports UTF-16 but actual language coverage depends on rmware and may be very limited. The encoding used on serial can be chosen with terminfo as either ASCII, UTF-8 or visual UTF-8. Last one is against the specication but results in correct rendering of right-to-left on some readers which dont have own bidi implementation. When using gfxterm or gfxmenu GRUB itself is responsible for rendering the text. In this case GRUB is limited by loaded fonts. If fonts contain all required characters then bidirectional text, cursive variants and combining marks other than enclosing, half (e.g. left half tilde or combining overline) and double ones. Ligatures arent supported though. This should cover European, Middle Eastern (if you dont mind lack of lam-alif ligature in Arabic) and East Asian scripts. Notable unsupported scripts are Brahmic family and derived as well as Mongolian, Tinagh, Korean Jamo (precomposed characters have no problem) and tonal writing (2e5-2e9). GRUB also ignores deprecated (as specied in Unicode) characters (e.g. tags). GRUB also doesnt handle so called annotation characters If you can complete either of two lists or, better, propose a patch to improve rendering, please contact developper team.
73
18 Input terminal
Firmware console on BIOS, IEEE1275 and ARC doesnt allow you to enter non-ASCII characters. EFI specication allows for such but author is unaware of any actual implementations. Serial input is currently limited for latin1 (unlikely to change). Own keyboard implementations (at keyboard and usb keyboard) supports any key but work on one-charper-keystroke. So no dead keys or advanced input method. Also there is no keymap change hotkey. In practice it makes dicult to enter any text using non-Latin alphabet. Moreover all current input consumers are limited to ASCII.
75
19 Gettext
GRUB supports being translated. For this you need to have language *.mo les in $prex/locale, load gettext module and set lang variable.
77
20 Regexp
Regexps work on unicode characters, however no attempt at checking cannonical equivalence has been made. Moreover the classes like [:alpha:] match only ASCII subset.
79
21 Other
Currently GRUB always uses YEAR-MONTH-DAY HOUR:MINUTE:SECOND [WEEKDAY] 24-hour datetime format but weekdays are translated. GRUB always uses the decimal number format with [0-9] as digits and . as descimal separator and no group separator. IEEE1275 aliases are matched case-insensitively except non-ASCII which is matched as binary. Similar behaviour is for matching OSBundleRequired. Since IEEE1275 aliases and OSBundleRequired dont contain any non-ASCII it should never be a problem in practice. Case-sensitive identiers are matched as raw strings, no canonical equivalence check is performed. Case-insenstive identiers are matched as RAW but additionally [a-z] is equivalent to [A-Z]. GRUB-dened identiers use only ASCII and so should user-dened ones. Identiers containing non-ASCII may work but arent supported. Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and LF U+000a) are recognised. Other unicode space characters arent a valid eld separator. test tests <, >, <=, >=, -pgt and -plt compare the strings in the lexicographical order of unicode codepoints, replicating the behaviour of test from coreutils. environment variables and commands are listed in the same order.
81
82
83
23 Platform limitations
GRUB2 is designed to be portable and is actually ported across platforms. We try to keep all platforms at the level. Unfortunately some platforms are better supported than others. This is detailed in current and 2 following sections. ARC platform is unable to change datetime (rmware doesnt seem to provide a function for it). EMU has similar limitation. ARC platform no serial port is available. EMU has similar limitation. Console charset refers only to rmware-assisted console. gfxterm is always Unicode (see Internationalisation section for its limitations). Serial is congurable to UTF-8 or ASCII (see Internationalisation). In case of qemu and coreboot ports the refered console is vga text. Loongson always uses gfxterm. Most limited one is ASCII. CP437 provides additionally pseudographics. GRUB2 doesnt use any language characters from CP437 as often CP437 is replaced by national encoding compatible only in pseudographics. Unicode is the most versatile charset which supports many languages. However the actual console may be much more limited depending on rmware On BIOS network is supported only if the image is loaded through network. On sparc64 GRUB is unable to determine which server it was booted from. On platforms not having direct serial support (as indicated in the line serial) you can still redirect rmware console to serial if it allows so. Direct ATA/AHCI support allows to circumvent various rmware limitations but isnt needed for normal operation except on baremetal ports. AT keyboard support allows keyboard layout remapping and support for keys not available through rmware. It isnt needed for normal operation except baremetal ports. USB support provides benets similar to ATA (for USB disks) or AT (for USB keyboards). In addition it allows USBserial. Chainloading refers to the ability to load another bootloader through the same protocol Hints allow faster disk discovery by already knowing in advance which is the disk in question. On some platforms hints are correct unless you move the disk between boots. On other platforms its just an educated guess. Note that hint failure results in just reduced performance, not a failure BadRAM is the ability to mark some of the RAM as bad. Note: due to protocol limitations mips-loongson (with Linux protocol) and mips-qemu mips can use only memory up to rst hole. BIOS Coreboot Multiboot Qemu video yes yes yes yes console charset CP437 CP437 CP437 CP437 network yes (*) no no no ATA/AHCI yes yes yes yes AT keyboard yes yes yes yes USB yes yes yes yes chainloader local yes yes no
84
cpuid hints PCI badram compression exit video console charset network ATA/AHCI AT keyboard USB chainloader cpuid hints PCI badram compression exit video console charset network ATA/AHCI AT keyboard USB chainloader cpuid hints PCI badram compression exit video console charset network ATA/AHCI AT keyboard USB chainloader cpuid hints PCI badram
partial guess yes yes always yes ia32 EFI yes Unicode yes yes yes yes local partial guess yes yes no yes Loongson yes N/A no yes yes yes yes no good yes yes (*) congurable no MIPS qemu no CP437 no yes yes N/A yes no guess no yes (*)
partial guess yes yes pointless no amd64 EFI yes Unicode yes yes yes yes local partial guess yes yes no yes sparc64 no ASCII yes (*) no no no no no good no no no yes emu yes ASCII yes no no yes no no no no no
partial guess yes yes no no ia32 IEEE1275 no ASCII yes yes yes yes no partial good yes no no yes Powerpc yes ASCII yes no no no no no good no no no yes
partial guess yes yes no no Itanium no Unicode yes no no no local no guess no yes no yes ARC no ASCII no no no no no no no no no congurable yes
85
compression exit
congurable no
no yes
87
24 Outline
Some platforms have features which allows to implement some commands useless or not implementable on others. Quick summary: Information retrieval: mipsel-loongson: lsspd mips-arc: lsdev e: lsesystab, lssal, lsemmap i386-pc: lsapm acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-e): lsacpi Workarounds for platform-specic issues: i386-e/x86 64-e: loadbios, xvideo acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-e): acpi (override ACPI tables) i386-pc: drivemap i386-pc: sendkey
Advanced operations for power users: x86: iorw (direct access to I/O ports) Miscelaneous: cmos (x86-*, ieee1275, mips-qemu mips, mips-loongson): cmostest (used on some laptops to check for special power-on key) i386-pc: play
89
90
32-bit Linux (modern protocol) 64-bit Linux (modern protocol) 32-bit XNU 64-bit XNU 32-bit EFI chainloader 64-bit EFI chainloader Appleloader BIOS chainloading NTLDR Plan9 FreeDOS FreeBSD bootloader 32-bit kFreeBSD 64-bit kFreeBSD 32-bit kNetBSD 64-bit kNetBSD 32-bit kOpenBSD 64-bit kOpenBSD Multiboot Multiboot2 32-bit Linux (legacy protocol) 64-bit Linux (legacy protocol) 32-bit Linux (modern protocol) 64-bit Linux (modern protocol) 32-bit XNU 64-bit XNU 32-bit EFI chainloader 64-bit EFI chainloader Appleloader BIOS chainloading NTLDR Plan9 FreeDOS FreeBSD bootloader 32-bit kFreeBSD 64-bit kFreeBSD 32-bit kNetBSD 64-bit kNetBSD 32-bit kOpenBSD 64-bit kOpenBSD Multiboot Multiboot2 32-bit Linux (legacy protocol) 64-bit Linux (legacy protocol)
yes yes ? ? no (3) no (3) no (3) ia32 EFI no (1) no (1) no (1) no (1) crashes (1) headless headless crashes (1) yes headless headless yes yes no (1) no (1) yes yes yes yes (5) yes no (4) yes ia32 IEEE1275 no (1) no (1) no (1) no (1) crashes (1) crashes (6) crashes (6) crashes (1) ? ? ? ? ? no (1) no (1)
yes yes ? ? no (3) no (3) no (3) amd64 EFI no (1) no (1) no (1) no (1) crashes (1) headless headless crashes (1) yes headless headless yes yes no (1) no (1) yes yes yes yes no (4) yes yes
91
32-bit Linux (modern protocol) ? 64-bit Linux (modern protocol) ? 32-bit XNU ? 64-bit XNU ? 32-bit EFI chainloader no (3) 64-bit EFI chainloader no (3) Appleloader no (3) 1. Requires BIOS 2. Crashes because the memory at 0x0-0x1000 isnt available 3. EFI only 4. 32-bit and 64-bit EFI have dierent structures and work in dierent CPU modes so its not possible to chainload 32-bit bootloader on 64-bit platform and vice-versa 5. Some modules may need to be disabled 6. Requires ACPI PowerPC, IA64 and Sparc64 ports support only Linux. MIPS port supports Linux and multiboot2.
93
26 Boot tests
As you have seen in previous chapter the support matrix is pretty big and some of the congurations 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. Following variables must be dened: GRUB PAYLOADS DIR directory containing the required kernels GRUB CBFSTOOL cbfstoll from Coreboot package (for coreboot platform only) GRUB COREBOOT ROM empty Coreboot ROM additional options to be supplied to QEMU GRUB QEMU OPTS Required les are: kfreebsd env.i386 32-bit kFreeBSD device hints kfreebsd.i386 32-bit FreeBSD kernel image kfreebsd.x86 64, same from 64-bit kFreeBSD kfreebsd env.x86 64 knetbsd.i386 32-bit NetBSD kernel image knetbsd.miniroot.i386 32-bit kNetBSD miniroot.kmod. same from 64-bit kNetBSD knetbsd.x86 64, knetbsd.miniroot.x86 64 kopenbsd.i386 32-bit OpenBSD kernel bsd.rd image kopenbsd.x86 64 same from 64-bit kOpenBSD linux.i386 32-bit Linux linux.x86 64 64-bit Linux
95
97
28 Invoking grub-install
The program grub-install installs GRUB on your drive using grub-mkimage and (on some platforms) grub-setup. You must specify the device name on which you want to install GRUB, like this: grub-install install_device The device name install device is an OS device name or a GRUB device name. grub-install accepts the following options: --help Print a summary of the command-line options and exit.
--version Print the version number of GRUB and exit. --boot-directory=dir Install GRUB images under the directory dir /grub/ This option is useful when you want to install GRUB into a separate partition or a removable disk. If this option is not specied then it defaults to /boot, so grub-install /dev/sda is equivalent to grub-install --boot-directory=/boot/ /dev/sda Here is an example in which you have a separate boot partition which is mounted on /mnt/boot: grub-install --boot-directory=/mnt/boot /dev/sdb --recheck Recheck the device map, even if /boot/grub/device.map already exists. You should use this option whenever you add/remove a disk into/from your computer.
99
29 Invoking grub-mkcong
The program grub-mkconfig generates a conguration le for GRUB (see Section 5.1 [Simple conguration], page 17). grub-mkconfig -o /boot/grub/grub.cfg grub-mkconfig accepts the following options: --help Print a summary of the command-line options and exit.
--version Print the version number of GRUB and exit. -o file --output=file Send the generated conguration le to le. The default is to send it to standard output.
101
30 Invoking grub-mkpasswd-pbkdf2
The program grub-mkpasswd-pbkdf2 generates password hashes for GRUB (see Chapter 22 [Security], page 81). grub-mkpasswd-pbkdf2 grub-mkpasswd-pbkdf2 accepts the following options: -c number --iteration-count=number Number of iterations of the underlying pseudo-random function. Defaults to 10000. -l number --buflen=number Length of the generated hash. Defaults to 64. -s number --salt=number Length of the salt. Defaults to 64.
103
31 Invoking grub-mkrescue
The program grub-mkrescue generates a bootable GRUB rescue image (see Section 3.2 [Making a GRUB bootable CD-ROM], page 10). grub-mkrescue -o grub.iso All arguments not explicitly listed as grub-mkrescue options are passed on directly to xorriso in mkisofs emulation mode. Options passed to xorriso will normally be interpreted as mkisofs options; if the option -- is used, then anything after that will be interpreted as native xorriso options. Non-option arguments specify additional source directories. This is commonly used to add extra les to the image: mkdir -p disk/boot/grub (add extra les to disk/boot/grub) grub-mkrescue -o grub.iso disk grub-mkrescue accepts the following options: --help Print a summary of the command-line options and exit.
--version Print the version number of GRUB and exit. -o file --output=file Save output in le. This "option" is required. --modules=modules Pre-load the named GRUB modules in the image. Multiple entries in modules should be separated by whitespace (so you will probably need to quote this for your shell). --rom-directory=dir If generating images for the QEMU or Coreboot platforms, copy the resulting qemu.img or coreboot.elf les respectively to the dir directory as well as including them in the image. --xorriso=file Use le as the xorriso program, rather than the built-in default. --grub-mkimage=file Use le as the grub-mkimage program, rather than the built-in default.
105
32 Invoking grub-probe
The program grub-probe probes device information for a given path or device. grub-probe --target=fs /boot/grub grub-probe --target=drive --device /dev/sda1 grub-probe must be given a path or device as a non-option argument, and also accepts the following options: --help Print a summary of the command-line options and exit. --version Print the version number of GRUB and exit. -d --device If this option is given, then the non-option argument is a system device name (such as /dev/sda1), and grub-probe will print information about that device. If it is not given, then the non-option argument is a lesystem path (such as /boot/grub), and grub-probe will print information about the device containing that part of the lesystem. -m file --device-map=file Use le as the device map (see Section 3.3 [Device map], page 10) rather than the default, usually /boot/grub/device.map. -t target --target=target Print information about the given path or device as dened by target. The available targets and their meanings are: fs fs_uuid fs_label Filesystem label. drive device partmap GRUB device name. System device name. GRUB partition map module. GRUB lesystem module. Filesystem Universally Unique Identier (UUID).
abstraction GRUB abstraction module (e.g. lvm). cryptodisk_uuid Crypto device UUID. msdos_parttype MBR partition type code (two hexadecimal digits). hints_string A string of platform search hints suitable for passing to the search command (see Section 14.3.40 [search], page 63).
106
bios_hints Search hints for the PC BIOS platform. ieee1275_hints Search hints for the IEEE1275 platform. baremetal_hints Search hints for platforms where disks are addressed directly rather than via rmware. efi_hints Search hints for the EFI platform. arc_hints Search hints for the ARC platform. compatibility_hint A guess at a reasonable GRUB drive name for this device, which may be used as a fallback if the search command fails. disk System device name for the whole disk.
107
Caution: GRUB requires binutils-2.9.1.0.23 or later because the GNU assembler has been changed so that it can produce real 16bits machine code between 2.9.1 and 2.9.1.0.x. See http://sources.redhat.com/binutils/, to obtain information on how to get the latest version. GRUB is available from the GNU alpha archive site ftp://ftp.gnu.org/gnu/grub or any of its mirrors. The le will be named grub-version.tar.gz. The current version is 2.00, so the le you should grab is: ftp://ftp.gnu.org/gnu/grub/grub-2.00.tar.gz To unbundle GRUB use the instruction: zcat grub-2.00.tar.gz | tar xvf which will create a directory called grub-2.00 with all the sources. You can look at the le INSTALL for detailed instructions on how to build and install GRUB, but you should be able to just do: cd grub-2.00 ./configure make install Also, the latest version is available using Bazaar. See http://www.gnu.org/software/grub/grub-downl for more information.
109
111
113
114
The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not t the above denition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A Transparent copy of the Document means a machine-readable copy, represented in a format whose specication is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent le format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modication by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not Transparent is called Opaque. Examples of suitable formats for Transparent copies include plain ascii without markup, Texinfo input format, LaTEX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modication. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the works title, preceding the beginning of the body of the text. A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specic section name mentioned below, such as Acknowledgements, Dedications, Endorsements, or History.) To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this denition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no eect on the meaning of this License. 2. VERBATIM COPYING
115
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Documents license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to t legibly, you should put the rst ones listed (as many as t reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modied Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modied Version under precisely this License, with the Modied Version lling the role of the Document, thus licensing distribution and modication of the Modied Version to whoever possesses a copy of it. In addition, you must do these things in the Modied Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any,
116
be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modications in the Modied Version, together with at least ve of the principal authors of the Document (all of its principal authors, if it has fewer than ve), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modied Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modied Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Documents license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled History, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modied Version as given on the Title Page. If there is no section Entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modied Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled Acknowledgements or Dedications, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled Endorsements. Such a section may not be included in the Modied Version. N. Do not retitle any existing section to be Entitled Endorsements or to conict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modied Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their
117
titles to the list of Invariant Sections in the Modied Versions license notice. These titles must be distinct from any other section titles. You may add a section Entitled Endorsements, provided it contains nothing but endorsements of your Modied Version by various partiesfor example, statements of peer review or that the text has been approved by an organization as the authoritative denition of a standard. You may add a passage of up to ve words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modied Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modied Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms dened in section 4 above for modied versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodied, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but dierent contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled History in the various original documents, forming one section Entitled History; likewise combine any sections Entitled Acknowledgements, and any sections Entitled Dedications. You must delete all sections Entitled Endorsements. 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
118
7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the compilations users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Documents Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modication, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled Acknowledgements, Dedications, or History, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may dier in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document species that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specied version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
119
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the with...Texts. line with this:
with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Index
121
Index
A
acpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
L
linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . linux16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . list_env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . load_env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . loopback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 60 60 60 60 61
B
badram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 blocklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
C
cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . chainloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . configfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cpuid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . crc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 56 56 57 57 57
M
menuentry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
N
normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 normal_exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
D
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 drivemap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
P
parttool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password_pbkdf2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pxe_unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 62 62 62 62
E
echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
F
false . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 FDL, GNU Free Documentation License . . . . . . 113
R
read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
G
gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 gptsync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
S
save_env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . submenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 63 63 54 66 53
H
halt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
T I
initrd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 initrd16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 insmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 terminal_input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminal_output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 54 55 66
K
keystatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
U
unset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66