| This is /home/phcoder/grub2/bzr/mainline/docs/grub.info, produced by |
| makeinfo version 4.13 from |
| /home/phcoder/grub2/bzr/mainline/docs/grub.texi. |
| |
| 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. |
| |
| INFO-DIR-SECTION Kernel |
| START-INFO-DIR-ENTRY |
| * GRUB: (grub). The GRand Unified Bootloader |
| * grub-install: (grub)Invoking grub-install. Install GRUB on your drive |
| * grub-mkconfig: (grub)Invoking grub-mkconfig. Generate GRUB configuration |
| * grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2. |
| * grub-mkrescue: (grub)Invoking grub-mkrescue. Make a GRUB rescue image |
| * grub-probe: (grub)Invoking grub-probe. Probe device information |
| END-INFO-DIR-ENTRY |
| |
| |
| File: grub.info, Node: Top, Next: Introduction, Up: (dir) |
| |
| GNU GRUB manual |
| *************** |
| |
| This is the documentation of GNU GRUB, the GRand Unified Bootloader, a |
| flexible and powerful boot loader program for a wide range of |
| architectures. |
| |
| This edition documents version 2.00. |
| |
| 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. |
| |
| * Menu: |
| |
| * Introduction:: Capturing the spirit of GRUB |
| * Naming convention:: Names of your drives in GRUB |
| * Installation:: Installing GRUB on your drive |
| * Booting:: How to boot different operating systems |
| * Configuration:: Writing your own configuration file |
| * Theme file format:: Format of GRUB theme files |
| * Network:: Downloading OS images from a network |
| * Serial terminal:: Using GRUB via a serial line |
| * Vendor power-on keys:: Changing GRUB behaviour on vendor power-on keys |
| * Images:: GRUB image files |
| * Filesystem:: Filesystem syntax and semantics |
| * Interface:: The menu and the command-line |
| * Environment:: GRUB environment variables |
| * Commands:: The list of available builtin commands |
| * Internationalisation:: Topics relating to language support |
| * Security:: Authentication and authorisation |
| * Platform limitations:: The list of platform-specific limitations |
| * Platform-specific operations:: Platform-specific operations |
| * Supported kernels:: The list of supported kernels |
| * Troubleshooting:: Error messages produced by GRUB |
| * Invoking grub-install:: How to use the GRUB installer |
| * Invoking grub-mkconfig:: Generate a GRUB configuration file |
| * Invoking grub-mkpasswd-pbkdf2:: |
| Generate GRUB password hashes |
| * Invoking grub-mkrescue:: Make a GRUB rescue image |
| * Invoking grub-probe:: Probe device information for GRUB |
| * Obtaining and Building GRUB:: How to obtain and build GRUB |
| * Reporting bugs:: Where you should send a bug report |
| * Future:: Some future plans on GRUB |
| * Copying This Manual:: Copying This Manual |
| * Index:: |
| |
| |
| File: grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top |
| |
| 1 Introduction to GRUB |
| ********************** |
| |
| * Menu: |
| |
| * Overview:: What exactly GRUB is and how to use it |
| * History:: From maggot to house fly |
| * Changes from GRUB Legacy:: Differences from previous versions |
| * Features:: GRUB features |
| * Role of a boot loader:: The role of a boot loader |
| |
| |
| File: grub.info, Node: Overview, Next: History, Up: Introduction |
| |
| 1.1 Overview |
| ============ |
| |
| Briefly, a "boot loader" is the first software program that runs when a |
| computer starts. It is responsible for loading and transferring |
| control to an operating system "kernel" software (such as Linux or GNU |
| Mach). The kernel, in turn, initializes the rest of the operating |
| system (e.g. a GNU system). |
| |
| GNU GRUB is a very powerful boot loader, which can load a wide |
| variety of free operating systems, as well as proprietary operating |
| systems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is |
| designed to address the complexity of booting a personal computer; both |
| the program and this manual are tightly bound to that computer platform, |
| although porting to other platforms may be addressed in the future. |
| |
| One of the important features in GRUB is flexibility; GRUB |
| understands filesystems and kernel executable formats, so you can load |
| an arbitrary operating system the way you like, without recording the |
| physical position of your kernel on the disk. Thus you can load the |
| kernel just by specifying its file name and the drive and partition |
| where the kernel resides. |
| |
| When booting with GRUB, you can use either a command-line interface |
| (*note Command-line interface::), or a menu interface (*note Menu |
| interface::). Using the command-line interface, you type the drive |
| specification and file name of the kernel manually. In the menu |
| interface, you just select an OS using the arrow keys. The menu is |
| based on a configuration file which you prepare beforehand (*note |
| Configuration::). While in the menu, you can switch to the command-line |
| mode, and vice-versa. You can even edit menu entries before using them. |
| |
| In the following chapters, you will learn how to specify a drive, a |
| partition, and a file name (*note Naming convention::) to GRUB, how to |
| install GRUB on your drive (*note Installation::), and how to boot your |
| OSes (*note Booting::), step by step. |
| |
| |
| File: grub.info, Node: Overview-Footnotes, Up: Overview |
| |
| (1) "chain-load" is the mechanism for loading unsupported operating |
| systems by loading another boot loader. It is typically used for |
| loading DOS or Windows. |
| |
| |
| File: grub.info, Node: History, Next: Changes from GRUB Legacy, Prev: Overview, Up: Introduction |
| |
| 1.2 History of GRUB |
| =================== |
| |
| GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU |
| Hurd with the University of Utah's Mach 4 microkernel (now known as GNU |
| Mach). Erich and Brian Ford designed the Multiboot Specification |
| (*note Multiboot Specification: (multiboot)Top.), because they were |
| determined not to add to the large number of mutually-incompatible PC |
| boot methods. |
| |
| Erich then began modifying the FreeBSD boot loader so that it would |
| understand Multiboot. He soon realized that it would be a lot easier to |
| write his own boot loader from scratch than to keep working on the |
| FreeBSD boot loader, and so GRUB was born. |
| |
| Erich added many features to GRUB, but other priorities prevented him |
| from keeping up with the demands of its quickly-expanding user base. In |
| 1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an |
| official GNU package, and opened its development by making the latest |
| sources available via anonymous CVS. *Note Obtaining and Building |
| GRUB::, 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 |
| difficult to make any further changes without breaking existing |
| features. Around 2002, Yoshinori K. Okuji started work on PUPA |
| (Preliminary Universal Programming Architecture for GNU GRUB), aiming |
| to rewrite the core of GRUB to make it cleaner, safer, more robust, and |
| more powerful. PUPA was eventually renamed to GRUB 2, and the original |
| version of GRUB was renamed to GRUB Legacy. Small amounts of |
| maintenance continued to be done on GRUB Legacy, but the last release |
| (0.97) was made in 2005 and at the time of writing it seems unlikely |
| that there will be another. |
| |
| By around 2007, GNU/Linux distributions started to use GRUB 2 to |
| limited extents, and by the end of 2009 multiple major distributions |
| were installing it by default. |
| |
| |
| File: grub.info, Node: Changes from GRUB Legacy, Next: Features, Prev: History, Up: Introduction |
| |
| 1.3 Differences from previous versions |
| ====================================== |
| |
| GRUB 2 is a rewrite of GRUB (*note History::), although it shares many |
| characteristics with the previous version, now known as GRUB Legacy. |
| Users of GRUB Legacy may need some guidance to find their way around |
| this new version. |
| |
| * The configuration file has a new name (`grub.cfg' rather than |
| `menu.lst' or `grub.conf'), new syntax (*note Configuration::) and |
| many new commands (*note Commands::). Configuration cannot be |
| copied over directly, although most GRUB Legacy users should not |
| find the syntax too surprising. |
| |
| * `grub.cfg' is typically automatically generated by `grub-mkconfig' |
| (*note Simple configuration::). This makes it easier to handle |
| versioned kernel upgrades. |
| |
| * Partition numbers in GRUB device names now start at 1, not 0 |
| (*note Naming convention::). |
| |
| * The configuration file is now written in something closer to a full |
| scripting language: variables, conditionals, and loops are |
| available. |
| |
| * A small amount of persistent storage is available across reboots, |
| using the `save_env' and `load_env' commands in GRUB and the |
| `grub-editenv' utility. This is not available in all |
| configurations (*note Environment block::). |
| |
| * GRUB 2 has more reliable ways to find its own files and those of |
| target kernels on multiple-disk systems, and has commands (*note |
| search::) to find devices using file system labels or Universally |
| Unique Identifiers (UUIDs). |
| |
| * GRUB 2 is available for several other types of system in addition |
| to the PC BIOS systems supported by GRUB Legacy: PC EFI, PC |
| coreboot, PowerPC, SPARC, and MIPS Lemote Yeeloong are all |
| supported. |
| |
| * Many more file systems are supported, including but not limited to |
| ext4, HFS+, and NTFS. |
| |
| * GRUB 2 can read files directly from LVM and RAID devices. |
| |
| * A graphical terminal and a graphical menu system are available. |
| |
| * GRUB 2's interface can be translated, including menu entry names. |
| |
| * The image files (*note Images::) that make up GRUB have been |
| reorganised; Stage 1, Stage 1.5, and Stage 2 are no more. |
| |
| * GRUB 2 puts many facilities in dynamically loaded modules, |
| allowing the core image to be smaller, and allowing the core image |
| to be built in more flexible ways. |
| |
| |
| File: grub.info, Node: Features, Next: Role of a boot loader, Prev: Changes from GRUB Legacy, Up: Introduction |
| |
| 1.4 GRUB features |
| ================= |
| |
| The primary requirement for GRUB is that it be compliant with the |
| "Multiboot Specification", which is described in *note Multiboot |
| Specification: (multiboot)Top. |
| |
| The other goals, listed in approximate order of importance, are: |
| |
| * Basic functions must be straightforward for end-users. |
| |
| * Rich functionality to support kernel experts and designers. |
| |
| * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and |
| Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are |
| supported via a chain-loading function. |
| |
| Except for specific compatibility modes (chain-loading and the Linux |
| "piggyback" format), all kernels will be started in much the same state |
| as in the Multiboot Specification. Only kernels loaded at 1 megabyte or |
| above are presently supported. Any attempt to load below that boundary |
| will simply result in immediate failure and an error message reporting |
| the problem. |
| |
| In addition to the requirements above, GRUB has the following |
| features (note that the Multiboot Specification doesn't require all the |
| features that GRUB supports): |
| |
| Recognize multiple executable formats |
| Support many of the "a.out" variants plus "ELF". Symbol tables are |
| also loaded. |
| |
| Support non-Multiboot kernels |
| Support many of the various free 32-bit kernels that lack Multiboot |
| compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux). |
| Chain-loading of other boot loaders is also supported. |
| |
| Load multiples modules |
| Fully support the Multiboot feature of loading multiple modules. |
| |
| Load a configuration file |
| Support a human-readable text configuration file with preset boot |
| commands. You can also load another configuration file dynamically |
| and embed a preset configuration file in a GRUB image file. The |
| list of commands (*note Commands::) are a superset of those |
| supported on the command-line. An example configuration file is |
| provided in *note Configuration::. |
| |
| Provide a menu interface |
| A menu interface listing preset boot commands, with a programmable |
| timeout, is available. There is no fixed limit on the number of |
| boot entries, and the current implementation has space for several |
| hundred. |
| |
| Have a flexible command-line interface |
| A fairly flexible command-line interface, accessible from the menu, |
| is available to edit any preset commands, or write a new boot |
| command set from scratch. If no configuration file is present, |
| GRUB drops to the command-line. |
| |
| The list of commands (*note Commands::) are a subset of those |
| supported for configuration files. Editing commands closely |
| resembles the Bash command-line (*note Bash: (features)Command |
| Line Editing.), with <TAB>-completion of commands, devices, |
| partitions, and files in a directory depending on context. |
| |
| Support multiple filesystem types |
| Support multiple filesystem types transparently, plus a useful |
| explicit blocklist notation. The currently supported filesystem |
| 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 files), |
| "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 AES-GCM). *Note Filesystem::, for |
| more information. |
| |
| Support automatic decompression |
| Can decompress files which were compressed by `gzip' or `xz'(1) |
| (*note Features-Footnote-1::). This function is both automatic and |
| transparent to the user (i.e. all functions operate upon the |
| uncompressed contents of the specified files). This greatly |
| reduces a file size and loading time, a particularly great benefit |
| for floppies.(2) (*note Features-Footnote-2::) |
| |
| It is conceivable that some kernel modules should be loaded in a |
| compressed state, so a different module-loading command can be |
| specified to avoid uncompressing the modules. |
| |
| Access data on any installed device |
| Support reading data from any or all floppies or hard disk(s) |
| recognized by the BIOS, independent of the setting of the root |
| device. |
| |
| Be independent of drive geometry translations |
| Unlike many other boot loaders, GRUB makes the particular drive |
| translation irrelevant. A drive installed and running with one |
| translation may be converted to another translation without any |
| adverse effects or changes in GRUB's configuration. |
| |
| Detect all installed RAM |
| GRUB can generally find all the installed RAM on a PC-compatible |
| machine. It uses an advanced BIOS query technique for finding all |
| memory regions. As described on the Multiboot Specification (*note |
| Multiboot Specification: (multiboot)Top.), 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 can't universally solve this problem, as |
| there is no standard interface used in all machines. However, |
| several newer machines have the new interface, Logical Block |
| Address ("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. |
| |
| |
| File: grub.info, Node: Features-Footnotes, Up: Features |
| |
| (1) Only CRC32 data integrity check is supported (xz default is |
| CRC64 so one should use -check=crc32 option). LZMA BCJ filters are |
| supported. |
| |
| (2) There are a few pathological cases where loading a very badly |
| organized ELF kernel might take longer, but in practice this never |
| happen. |
| |
| |
| File: grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction |
| |
| 1.5 The role of a boot loader |
| ============================= |
| |
| The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: |
| |
| Some people like to acknowledge both the operating system and |
| kernel when they talk about their computers, so they might say |
| they use "GNU/Linux" or "GNU/Hurd". Other people seem to think |
| that the kernel is the most important part of the system, so they |
| like to call their GNU operating systems "Linux systems." |
| |
| I, personally, believe that this is a grave injustice, because the |
| _boot loader_ is the most important software of all. I used to |
| refer to the above systems as either "LILO"(1) (*note Role of a |
| boot loader-Footnote-1::) or "GRUB" systems. |
| |
| Unfortunately, nobody ever understood what I was talking about; |
| now I just use the word "GNU" as a pseudonym for GRUB. |
| |
| So, if you ever hear people talking about their alleged "GNU" |
| systems, remember that they are actually paying homage to the best |
| boot loader around... GRUB! |
| |
| We, the GRUB maintainers, do not (usually) encourage Gordon's level |
| of fanaticism, but it helps to remember that boot loaders deserve |
| recognition. We hope that you enjoy using GNU GRUB as much as we did |
| writing it. |
| |
| |
| File: grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader |
| |
| (1) The LInux LOader, a boot loader that everybody uses, but nobody |
| likes. |
| |
| |
| File: grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top |
| |
| 2 Naming convention |
| ******************* |
| |
| The device syntax used in GRUB is a wee bit different from what you may |
| have seen before in your operating system(s), and you need to know it so |
| that you can specify a drive/partition. |
| |
| Look at the following examples and explanations: |
| |
| (fd0) |
| |
| First of all, GRUB requires that the device name be enclosed with |
| `(' and `)'. The `fd' part means that it is a floppy disk. The number |
| `0' is the drive number, which is counted from _zero_. This expression |
| means that GRUB will use the whole floppy disk. |
| |
| (hd0,msdos2) |
| |
| Here, `hd' means it is a hard disk drive. The first integer `0' |
| indicates the drive number, that is, the first 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 first hard disk drive. In this case, |
| GRUB uses one partition of the disk, instead of the whole disk. |
| |
| (hd0,msdos5) |
| |
| This specifies the first "extended partition" of the first 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 first 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 specification in a command, like `set |
| root=(fd0)' or `parttool (hd0,msdos3) hidden-'. To help you find out |
| which number specifies a partition you want, the GRUB command-line |
| (*note Command-line interface::) 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 file 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 file? Again, consider an |
| example: |
| |
| (hd0,msdos1)/vmlinuz |
| |
| This specifies the file named `vmlinuz', found on the first |
| partition of the first hard disk drive. Note that the argument |
| completion works with file names, too. |
| |
| That was easy, admit it. Now read the next chapter, to find out how |
| to actually install GRUB on your drive. |
| |
| |
| File: grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top |
| |
| 3 Installation |
| ************** |
| |
| In order to install GRUB as your boot loader, you need to first install |
| the GRUB system and utilities under your UNIX-like operating system |
| (*note Obtaining and Building GRUB::). You can do this either from the |
| source tarball, or as a package for your OS. |
| |
| After you have done that, you need to install the boot loader on a |
| drive (floppy or hard disk) by using the utility `grub-install' (*note |
| Invoking grub-install::) 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 find them (usually `/boot') will be called the "boot |
| directory". |
| |
| * Menu: |
| |
| * Installing GRUB using grub-install:: |
| * Making a GRUB bootable CD-ROM:: |
| * Device map:: |
| * BIOS installation:: |
| |
| |
| File: grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Up: Installation |
| |
| 3.1 Installing GRUB using grub-install |
| ====================================== |
| |
| For information on where GRUB should be installed on PC BIOS platforms, |
| *note BIOS installation::. |
| |
| In order to install GRUB under a UNIX-like OS (such as GNU), invoke |
| the program `grub-install' (*note Invoking grub-install::) as the |
| superuser ("root"). |
| |
| The usage is basically very simple. You only need to specify one |
| argument to the program, namely, where to install the boot loader. The |
| argument has to be either a device file (like `/dev/hda'). For |
| example, under Linux the following will install GRUB into the MBR of |
| the first IDE disk: |
| |
| # grub-install /dev/hda |
| |
| Likewise, under GNU/Hurd, this has the same effect: |
| |
| # grub-install /dev/hd0 |
| |
| But all the above examples assume that GRUB should put images under |
| the `/boot' directory. If you want GRUB to put images under a directory |
| other than `/boot', you need to specify the option `--boot-directory'. |
| The typical usage is that you create a GRUB boot floppy with a |
| filesystem. Here is an example: |
| |
| # mke2fs /dev/fd0 |
| # mount -t ext2 /dev/fd0 /mnt |
| # mkdir /mnt/boot |
| # grub-install --boot-directory=/mnt/boot /dev/fd0 |
| # umount /mnt |
| |
| Some BIOSes have a bug of exposing the first partition of a USB |
| drive as a floppy instead of exposing the USB drive as a hard disk |
| (they call it "USB-FDD" boot). In such cases, you need to install like |
| this: |
| |
| # losetup /dev/loop0 /dev/sdb1 |
| # mount /dev/loop0 /mnt/usb |
| # grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0 |
| |
| This install doesn't conflict 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'. Don't do that, however, unless you are very familiar |
| with the internals of GRUB. Installing a boot loader on a running OS |
| may be extremely dangerous. |
| |
| |
| File: grub.info, Node: Making a GRUB bootable CD-ROM, Next: Device map, Prev: Installing GRUB using grub-install, Up: Installation |
| |
| 3.2 Making a GRUB bootable CD-ROM |
| ================================= |
| |
| GRUB supports the "no emulation mode" in the El Torito specification(1) |
| (*note Making a GRUB bootable CD-ROM-Footnote-1::). This means that you |
| can use the whole CD-ROM from GRUB and you don't have to make a floppy |
| or hard disk image file, which can cause compatibility problems. |
| |
| For booting from a CD-ROM, GRUB uses a special image called |
| `cdboot.img', which is concatenated with `core.img'. The `core.img' |
| used for this should be built with at least the `iso9660' and |
| `biosdisk' modules. Your bootable CD-ROM will usually also need to |
| include a configuration file `grub.cfg' and some other GRUB modules. |
| |
| To make a simple generic GRUB rescue CD, you can use the |
| `grub-mkrescue' program (*note Invoking grub-mkrescue::): |
| |
| $ grub-mkrescue -o grub.iso |
| |
| You will often need to include other files in your image. To do |
| this, first make a top directory for the bootable image, say, `iso': |
| |
| $ mkdir iso |
| |
| Make a directory for GRUB: |
| |
| $ mkdir -p iso/boot/grub |
| |
| If desired, make the config file `grub.cfg' under `iso/boot/grub' |
| (*note Configuration::), and copy any files and directories for the |
| disc to the directory `iso/'. |
| |
| Finally, make the image: |
| |
| $ grub-mkrescue -o grub.iso iso |
| |
| This produces a file named `grub.iso', which then can be burned into |
| a CD (or a DVD), or written to a USB mass storage device. |
| |
| The root device will be set up appropriately on entering your |
| `grub.cfg' configuration file, so you can refer to file names on the CD |
| without needing to use an explicit device name. This makes it easier to |
| produce rescue images that will work on both optical drives and USB mass |
| storage devices. |
| |
| |
| File: grub.info, Node: Making a GRUB bootable CD-ROM-Footnotes, Up: Making a GRUB bootable CD-ROM |
| |
| (1) El Torito is a specification for bootable CD using BIOS |
| functions. |
| |
| |
| File: grub.info, Node: Device map, Next: BIOS installation, Prev: Making a GRUB bootable CD-ROM, Up: Installation |
| |
| 3.3 The map between BIOS drives and OS devices |
| ============================================== |
| |
| If the device map file exists, the GRUB utilities (`grub-probe', |
| `grub-setup', etc.) read it to map BIOS drives to OS devices. This |
| file consists of lines like this: |
| |
| (DEVICE) FILE |
| |
| DEVICE is a drive specified in the GRUB syntax (*note Device |
| syntax::), and FILE is an OS file, which is normally a device file. |
| |
| Historically, the device map file was used because GRUB device names |
| had to be used in the configuration file, and they were derived from |
| BIOS drive numbers. The map between BIOS drives and OS devices cannot |
| always be guessed correctly: for example, GRUB will get the order wrong |
| if you exchange the boot sequence between IDE and SCSI in your BIOS. |
| |
| Unfortunately, even OS device names are not always stable. Modern |
| versions of the Linux kernel may probe drives in a different order from |
| boot to boot, and the prefix (`/dev/hd*' versus `/dev/sd*') may change |
| depending on the driver subsystem in use. As a result, the device map |
| file required frequent editing on some systems. |
| |
| GRUB avoids this problem nowadays by using UUIDs or file system |
| labels when generating `grub.cfg', and we advise that you do the same |
| for any custom menu entries you write. If the device map file does not |
| exist, then the GRUB utilities will assume a temporary device map on |
| the fly. This is often good enough, particularly in the common case of |
| single-disk systems. |
| |
| However, the device map file is not entirely obsolete yet, and it is |
| used for overriding when current environment is different from the one |
| on boot. Most common case is if you use a partition or logical volume |
| as a disk for virtual machine. You can put any comments in the file if |
| needed, as the GRUB utilities assume that a line is just a comment if |
| the first character is `#'. |
| |
| |
| File: grub.info, Node: BIOS installation, Prev: Device map, Up: Installation |
| |
| 3.4 BIOS installation |
| ===================== |
| |
| MBR |
| === |
| |
| The partition table format traditionally used on PC BIOS platforms is |
| called the Master Boot Record (MBR) format; this is the format that |
| allows up to four primary partitions and additional logical partitions. |
| With this partition table format, there are two ways to install GRUB: |
| it can be embedded in the area between the MBR and the first partition |
| (called by various names, such as the "boot track", "MBR gap", or |
| "embedding area", and which is usually at least 31 KiB), or the core |
| image can be installed in a file system and a list of the blocks that |
| make it up can be stored in the first sector of that partition. |
| |
| Each of these has different problems. There is no way to reserve |
| space in the embedding area with complete safety, and some proprietary |
| software is known to use it to make it difficult for users to work |
| around licensing restrictions; and systems are sometimes partitioned |
| without leaving enough space before the first partition. On the other |
| hand, installing to a filesystem means that GRUB is vulnerable to its |
| blocks being moved around by filesystem features such as tail packing, |
| or even by aggressive fsck implementations, so this approach is quite |
| fragile; and this approach can only be used if the `/boot' filesystem |
| is on the same disk that the BIOS boots from, so that GRUB does not |
| have to rely on guessing BIOS drive numbers. |
| |
| The GRUB development team generally recommends embedding GRUB before |
| the first partition, unless you have special requirements. You must |
| ensure that the first partition starts at least 31 KiB (63 sectors) |
| from the start of the disk; on modern disks, it is often a performance |
| advantage to align partitions on larger boundaries anyway, so the first |
| partition might start 1 MiB from the start of the disk. |
| |
| GPT |
| === |
| |
| Some newer systems use the GUID Partition Table (GPT) format. This was |
| specified as part of the Extensible Firmware Interface (EFI), but it can |
| also be used on BIOS platforms if system software supports it; for |
| example, GRUB and GNU/Linux can be used in this configuration. With |
| this format, it is possible to reserve a whole partition for GRUB, |
| called the BIOS Boot Partition. GRUB can then be embedded into that |
| partition without the risk of being overwritten by other software and |
| without being contained in a filesystem which might move its blocks |
| around. |
| |
| When creating a BIOS Boot Partition on a GPT system, you should make |
| sure that it is at least 31 KiB in size. (GPT-formatted disks are not |
| usually particularly small, so we recommend that you make it larger |
| than the bare minimum, such as 1 MiB, to allow plenty of room for |
| growth.) You must also make sure that it has the proper partition |
| type. Using GNU Parted, you can set this using a command such as the |
| following: |
| |
| # 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 |
| finds a BIOS Boot Partition during installation, it will automatically |
| overwrite part of it. Make sure that the partition does not contain any |
| other data. |
| |
| |
| File: grub.info, Node: Booting, Next: Configuration, Prev: Installation, Up: Top |
| |
| 4 Booting |
| ********* |
| |
| GRUB can load Multiboot-compliant kernels in a consistent way, but for |
| some free operating systems you need to use some OS-specific magic. |
| |
| * Menu: |
| |
| * General boot methods:: How to boot OSes with GRUB generally |
| * Loopback booting:: Notes on booting from loopbacks |
| * OS-specific notes:: Notes on some operating systems |
| |
| |
| File: grub.info, Node: General boot methods, Next: Loopback booting, Up: Booting |
| |
| 4.1 How to boot operating systems |
| ================================= |
| |
| GRUB has two distinct boot methods. One of the two is to load an |
| operating system directly, and the other is to chain-load another boot |
| loader which then will load an operating system actually. Generally |
| speaking, the former is more desirable, because you don't need to |
| install or maintain other boot loaders and GRUB is flexible enough to |
| load an operating system from an arbitrary disk/partition. However, the |
| latter is sometimes required, since GRUB doesn't support all the |
| existing operating systems natively. |
| |
| * Menu: |
| |
| * Loading an operating system directly:: |
| * Chain-loading:: |
| |
| |
| File: grub.info, Node: Loading an operating system directly, Next: Chain-loading, Up: General boot methods |
| |
| 4.1.1 How to boot an OS directly with GRUB |
| ------------------------------------------ |
| |
| Multiboot (*note Multiboot Specification: (multiboot)Top.) is the |
| native format supported by GRUB. For the sake of convenience, there is |
| also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to |
| boot other operating systems, you will have to chain-load them (*note |
| Chain-loading::). |
| |
| FIXME: this section is incomplete. |
| |
| 1. Run the command `boot' (*note boot::). |
| |
| However, DOS and Windows have some deficiencies, so you might have to |
| use more complicated instructions. *Note DOS/Windows::, for more |
| information. |
| |
| |
| File: grub.info, Node: Chain-loading, Prev: Loading an operating system directly, Up: General boot methods |
| |
| 4.1.2 Chain-loading an OS |
| ------------------------- |
| |
| Operating systems that do not support Multiboot and do not have specific |
| support in GRUB (specific support is available for Linux, FreeBSD, |
| NetBSD and OpenBSD) must be chain-loaded, which involves loading |
| another boot loader and jumping to it in real mode. |
| |
| The `chainloader' command (*note chainloader::) is used to set this |
| up. It is normally also necessary to load some GRUB modules and set the |
| appropriate root device. Putting this together, we get something like |
| this, for a Windows system on the first partition of the first hard |
| disk: |
| |
| menuentry "Windows" { |
| insmod chain |
| insmod ntfs |
| set root=(hd0,1) |
| chainloader +1 |
| } |
| |
| On systems with multiple hard disks, an additional workaround may be |
| required. *Note DOS/Windows::. |
| |
| Chain-loading is only supported on PC BIOS and EFI platforms. |
| |
| |
| File: grub.info, Node: Loopback booting, Next: OS-specific notes, Prev: General boot methods, Up: Booting |
| |
| 4.2 Loopback booting |
| ==================== |
| |
| GRUB is able to read from an image (be it one of CD or HDD) stored on |
| any of its accessible storages (refer to *note loopback:: command). |
| However the OS itself should be able to find its root. This usually |
| involves running a userspace program running before the real root is |
| discovered. This is achieved by GRUB loading a specially made small |
| image and passing it as ramdisk to the kernel. This is achieved by |
| commands `kfreebsd_module', `knetbsd_module_elf', `kopenbsd_ramdisk', |
| `initrd' (*note initrd::), `initrd16' (*note initrd::), |
| `multiboot_module', `multiboot2_module' or `xnu_ramdisk' depending on |
| the loader. Note that for knetbsd the image must be put inside |
| miniroot.kmod and the whole miniroot.kmod has to be loaded. In kopenbsd |
| payload this is disabled by default. Aditionally behaviour of initial |
| ramdisk depends on command line options. Several distributors provide |
| the image for this purpose or it's integrated in their standard ramdisk |
| and activated by special option. Consult your kernel and distribution |
| manual for more details. Other loaders like appleloader, chainloader |
| (BIOS, EFI, coreboot), freedos, ntldr and plan9 provide no possibility |
| of loading initial ramdisk and as far as author is aware the payloads |
| in question don't support either initial ramdisk or discovering |
| loopback boot in other way and as such not bootable this way. Please |
| consider alternative boot methods like copying all files from the image |
| to actual partition. Consult your OS documentation for more details |
| |
| |
| File: grub.info, Node: OS-specific notes, Prev: Loopback booting, Up: Booting |
| |
| 4.3 Some caveats on OS-specific issues |
| ====================================== |
| |
| Here, we describe some caveats on several operating systems. |
| |
| * Menu: |
| |
| * GNU/Hurd:: |
| * GNU/Linux:: |
| * DOS/Windows:: |
| |
| |
| File: grub.info, Node: GNU/Hurd, Next: GNU/Linux, Up: OS-specific notes |
| |
| 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 GRUB's root device to the same drive as GNU/Hurd's. The |
| command `search --set=root --file /boot/gnumach.gz' or similar may |
| help you (*note search::). |
| |
| 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' (*note boot::). |
| |
| |
| File: grub.info, Node: GNU/Linux, Next: DOS/Windows, Prev: GNU/Hurd, Up: OS-specific notes |
| |
| 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. |
| |
| 1. Set GRUB's root device to the same drive as GNU/Linux's. The |
| command `search --set=root --file /vmlinuz' or similar may help you |
| (*note search::). |
| |
| 2. Load the kernel using the command `linux' (*note linux::): |
| |
| 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 aren't 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' (*note initrd::) |
| after `linux': |
| |
| grub> initrd /initrd |
| |
| If you used `linux16' you need to use `initrd16': |
| |
| grub> initrd16 /initrd |
| |
| 4. Finally, run the command `boot' (*note boot::). |
| |
| *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. *Note uppermem::, |
| for more information. |
| |
| |
| File: grub.info, Node: DOS/Windows, Prev: GNU/Linux, Up: OS-specific notes |
| |
| 4.3.3 DOS/Windows |
| ----------------- |
| |
| GRUB cannot boot DOS or Windows directly, so you must chain-load them |
| (*note Chain-loading::). However, their boot loaders have some critical |
| deficiencies, so it may not work to just chain-load them. To overcome |
| the problems, GRUB provides you with two helper functions. |
| |
| If you have installed DOS (or Windows) on a non-first hard disk, you |
| have to use the disk swapping technique, because that OS cannot boot |
| from any disks but the first one. The workaround used in GRUB is the |
| command `drivemap' (*note drivemap::), like this: |
| |
| drivemap -s (hd0) (hd1) |
| |
| This performs a "virtual" swap between your first and second hard |
| drive. |
| |
| *Caution:* This is effective only if DOS (or Windows) uses BIOS to |
| access the swapped disks. If that OS uses a special driver for the |
| disks, this probably won't work. |
| |
| Another problem arises if you installed more than one set of |
| DOS/Windows onto one disk, because they could be confused if there are |
| more than one primary partitions for DOS/Windows. Certainly you should |
| avoid doing this, but there is a solution if you do want to do so. Use |
| the partition hiding/unhiding technique. |
| |
| If GRUB "hides" a DOS (or Windows) partition (*note parttool::), DOS |
| (or Windows) will ignore the partition. If GRUB "unhides" a DOS (or |
| Windows) partition, DOS (or Windows) will detect the partition. Thus, |
| if you have installed DOS (or Windows) on the first and the second |
| partition of the first hard disk, and you want to boot the copy on the |
| first partition, do the following: |
| |
| parttool (hd0,1) hidden- |
| parttool (hd0,2) hidden+ |
| set root=(hd0,1) |
| chainloader +1 |
| parttool ${root} boot+ |
| boot |
| |
| |
| File: grub.info, Node: Configuration, Next: Theme file format, Prev: Booting, Up: Top |
| |
| 5 Writing your own configuration file |
| ************************************* |
| |
| GRUB is configured using `grub.cfg', usually located under |
| `/boot/grub'. This file is quite flexible, but most users will not |
| need to write the whole thing by hand. |
| |
| * Menu: |
| |
| * Simple configuration:: Recommended for most users |
| * Shell-like scripting:: For power users and developers |
| * Multi-boot manual config:: For non-standard multi-OS scenarios |
| * Embedded configuration:: Embedding a configuration file into GRUB |
| |
| |
| File: grub.info, Node: Simple configuration, Next: Shell-like scripting, Up: Configuration |
| |
| 5.1 Simple configuration handling |
| ================================= |
| |
| The program `grub-mkconfig' (*note Invoking grub-mkconfig::) generates |
| `grub.cfg' files suitable for most cases. It is suitable for use when |
| upgrading a distribution, and will discover available kernels and |
| attempt to generate menu entries for them. |
| |
| `grub-mkconfig' does have some limitations. While adding extra |
| custom menu entries to the end of the list can be done by editing |
| `/etc/grub.d/40_custom' or creating `/boot/grub/custom.cfg', changing |
| the order of menu entries or changing their titles may require making |
| complex changes to shell scripts stored in `/etc/grub.d/'. This may be |
| improved in the future. In the meantime, those who feel that it would |
| be easier to write `grub.cfg' directly are encouraged to do so (*note |
| Booting::, and *note Shell-like scripting::), and to disable any system |
| provided by their distribution to automatically run `grub-mkconfig'. |
| |
| The file `/etc/default/grub' controls the operation of |
| `grub-mkconfig'. It is sourced by a shell script, and so must be valid |
| POSIX shell input; normally, it will just be a sequence of `KEY=value' |
| lines, but if the value contains spaces or other special characters |
| then it must be quoted. For example: |
| |
| GRUB_TERMINAL_INPUT="console serial" |
| |
| Valid keys in `/etc/default/grub' are as follows: |
| |
| `GRUB_DEFAULT' |
| The default menu entry. This may be a number, in which case it |
| identifies the Nth entry in the generated menu counted from zero, |
| or the title of a menu entry, or the special string `saved'. |
| Using the title may be useful if you want to set a menu entry as |
| the default even though there may be a variable number of entries |
| before it. |
| |
| For example, if you have: |
| |
| menuentry 'Example GNU/Linux distribution' --class gnu-linux { |
| ... |
| } |
| |
| then you can make this the default using: |
| |
| GRUB_DEFAULT='Example GNU/Linux distribution' |
| |
| If you set this to `saved', then the default menu entry will be |
| that saved by `GRUB_SAVEDEFAULT', `grub-set-default', or |
| `grub-reboot'. |
| |
| The default is `0'. |
| |
| `GRUB_SAVEDEFAULT' |
| If this option is set to `true', then, when an entry is selected, |
| save it as a new default entry for use by future runs of GRUB. |
| This is only useful if `GRUB_DEFAULT=saved'; it is a separate |
| option because `GRUB_DEFAULT=saved' is useful without this option, |
| in conjunction with `grub-set-default' or `grub-reboot'. Unset by |
| default. This option relies on the environment block, which may |
| not be available in all situations (*note Environment block::). |
| |
| `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 indefinitely. |
| |
| `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 specified 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' |
| suffix, used to support vendor-specific power buttons. *Note |
| Vendor power-on keys::. |
| |
| `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 firmware |
| does not handle this). |
| |
| The default is to use the platform's 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' (graphics-mode output), `ofconsole' (Open Firmware |
| console), or `vga_text' (VGA text output, mainly useful with |
| Coreboot). |
| |
| The default is to use the platform's 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 configure the serial port when using the serial |
| console. *Note serial::. 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 |
| universally-unique identifiers (UUIDs) to identify the root |
| filesystem 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 `grub-mkconfig' will normally |
| load all available GRUB video drivers and use the one most |
| appropriate for your hardware. If you need to override this for |
| some reason, then you can set this option. |
| |
| After `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. *Note gfxmode::. |
| |
| `GRUB_BACKGROUND' |
| Set a background image for use with the `gfxterm' graphical |
| terminal. The value of this option must be a file readable by |
| GRUB at boot time, and it must end with `.png', `.tga', `.jpg', or |
| `.jpeg'. The image will be scaled if necessary to fit 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', `WIDTHxHEIGHT'[`xDEPTH'] to set a particular |
| graphics mode, or a sequence of these separated by commas or |
| semicolons to try several modes in sequence. *Note gfxpayload::. |
| |
| Depending on your kernel, your distribution, your graphics card, |
| and the phase of the moon, note that using this option may cause |
| GNU/Linux to suffer from various display problems, particularly |
| during the early part of the 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 *note play::. |
| |
| `GRUB_BADRAM' |
| If this option is set, GRUB will issue a *note badram:: command to |
| filter out specified 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'. |
| |
| |
| For more detailed customisation of `grub-mkconfig''s 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 file, making sure |
| to leave at least the first two lines intact. |
| |
| |
| File: grub.info, Node: Shell-like scripting, Next: Multi-boot manual config, Prev: Simple configuration, Up: Configuration |
| |
| 5.2 Writing full configuration files directly |
| ============================================= |
| |
| `grub.cfg' is written in GRUB's built-in scripting language, which has |
| a syntax quite similar to that of GNU Bash and other Bourne shell |
| derivatives. |
| |
| 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 first 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 effectively ignored(1) (*note |
| Shell-like scripting-Footnote-1::)). 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 (*note Environment::). |
| |
| Positional variable names consist of one or more digits. They |
| represent parameters passed to function calls, with `$1' representing |
| the first 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 defined 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 first word specifies |
| 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 command's 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;] fi |
| 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 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 defines 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 specified as the name of a |
| simple command. Function definitions do not affect 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; ... } |
| *Note menuentry::. |
| |
| 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 |
| specified, 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. |
| |
| continue [`n'] |
| Resume the next iteration of the enclosing `for', `while' or |
| `until' loop. If `n' is specified, resume at the `n'th 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 specified 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. |
| |
| shift [`n'] |
| 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 non-negative 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 parameters are not changed. The return status is |
| greater than zero if `n' is greater than `$#' or less than zero; |
| otherwise 0. |
| |
| |
| |
| File: grub.info, Node: Shell-like scripting-Footnotes, Up: Shell-like scripting |
| |
| (1) Currently a backslash-newline pair within a variable name is not |
| handled properly, so use this feature with some care. |
| |
| |
| File: grub.info, Node: Multi-boot manual config, Next: Embedded configuration, Prev: Shell-like scripting, Up: Configuration |
| |
| 5.3 Multi-boot manual config |
| ============================ |
| |
| Currently autogenerating config files for multi-boot environments |
| depends on os-prober and has several shortcomings. While fixing it is |
| scheduled for the next release, meanwhile you can make use of the power |
| of GRUB syntax and do it yourself. A possible configuration is detailed |
| here, feel free to adjust to your needs. |
| |
| First create a separate GRUB partition, big enough to hold GRUB. |
| Some of the following entries show how to load OS installer images from |
| this same partition, for that you obviously need to make the partition |
| large enough to hold those images as well. Mount this partition |
| on/mnt/boot and disable GRUB in all OSes and manually install |
| self-compiled latest GRUB with: |
| |
| `grub-install --boot-directory=/mnt/boot /dev/sda' |
| |
| In all the OSes install GRUB tools but disable installing GRUB in |
| bootsector, so you'll have menu.lst and grub.cfg available for use. |
| Also disable os-prober use by setting: |
| |
| `GRUB_DISABLE_OS_PROBER=true' |
| |
| in /etc/default/grub |
| |
| Then write a grub.cfg (/mnt/boot/grub/grub.cfg): |
| |
| |
| menuentry "OS using grub2" { |
| insmod xfs |
| search --set=root --label OS1 --hint hd0,msdos8 |
| configfile /boot/grub/grub.cfg |
| } |
| |
| menuentry "OS using grub2-legacy" { |
| insmod ext2 |
| search --set=root --label OS2 --hint hd0,msdos6 |
| legacy_configfile /boot/grub/menu.lst |
| } |
| |
| menuentry "Windows XP" { |
| insmod ntfs |
| search --set=root --label WINDOWS_XP --hint hd0,msdos1 |
| ntldr /ntldr |
| } |
| |
| menuentry "Windows 7" { |
| insmod ntfs |
| search --set=root --label WINDOWS_7 --hint hd0,msdos2 |
| ntldr /bootmgr |
| } |
| |
| menuentry "FreeBSD" { |
| 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/development/rawhide/x86_64 lang=en_US keymap=sg resolution=1280x800 |
| 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.gz |
| } |
| |
| 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. |
| |
| |
| File: grub.info, Node: Embedded configuration, Prev: Multi-boot manual config, Up: Configuration |
| |
| 5.4 Embedding a configuration file into GRUB |
| ============================================ |
| |
| GRUB supports embedding a configuration file directly into the core |
| image, so that it is loaded before entering normal mode. This is |
| useful, for example, when it is not straightforward to find the real |
| configuration file, or when you need to debug problems with loading |
| that file. `grub-install' uses this feature when it is not using BIOS |
| disk functions or when installing to a different disk from the one |
| containing `/boot/grub', in which case it needs to use the `search' |
| command (*note search::) to find `/boot/grub'. |
| |
| To embed a configuration file, use the `-c' option to |
| `grub-mkimage'. The file is copied into the core image, so it may |
| reside anywhere on the file system, and may be removed after running |
| `grub-mkimage'. |
| |
| After the embedded configuration file (if any) is executed, GRUB |
| will load the `normal' module (*note normal::), which will then read |
| the real configuration file 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 configuration |
| file only needs to set the `prefix' and `root' variables, and then drop |
| through to GRUB's 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 configuration |
| files directly from the embedded configuration file. This allows such |
| things as reading files not called `grub.cfg', or reading files from a |
| directory other than that where GRUB's loadable modules are installed. |
| To do this, include the `configfile' and `normal' modules in the core |
| image, and embed a configuration file that uses the `configfile' |
| command to load another file. 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 configuration file may not contain menu entries |
| directly, but may only read them from elsewhere using `configfile'. |
| |
| |
| File: grub.info, Node: Theme file format, Next: Network, Prev: Configuration, Up: Top |
| |
| 6 Theme file 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 configured through |
| a plain text file that specifies the layout of the various GUI |
| components (including the boot menu, timeout progress bar, and text |
| messages) as well as the appearance using colors, fonts, and images. |
| Example is available in docs/example_theme.txt |
| |
| 6.2 Theme Elements |
| ================== |
| |
| 6.2.1 Colors |
| ------------ |
| |
| Colors can be specified in several ways: |
| |
| * HTML-style "#RRGGBB" or "#RGB" format, where *R*, *G*, and *B* are |
| hexadecimal digits (e.g., "#8899FF") |
| |
| * as comma-separated decimal RGB values (e.g., "128, 128, 255") |
| |
| * with "SVG 1.0 color names" (e.g., "cornflowerblue") which must be |
| specified in lowercase. |
| |
| 6.2.2 Fonts |
| ----------- |
| |
| The fonts GRUB uses "PFF2 font format" bitmap fonts. Fonts are |
| specified with full font names. Currently there is no provision for a |
| preference list of fonts, or deriving one font from another. 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 |
| fit on screen, do "set pager=1" before executing "lsfonts". |
| |
| 6.2.3 Progress Bar |
| ------------------ |
| |
| Figure 6.1 |
| |
| Figure 6.2 |
| |
| Progress bars are used to display the remaining time before GRUB |
| boots the default menu entry. To create a progress bar that will |
| display the remaining time before automatic boot, simply create a |
| "progress_bar" component with the id "__timeout__". This indicates to |
| GRUB that the progress bar should be updated as time passes, and it |
| should be made invisible if the countdown to automatic boot is |
| interrupted by the user. |
| |
| Progress bars may optionally have text displayed on them. This text |
| is controlled by variable "text" which contains a printf template with |
| the only argument %d is the number of seconds remaining. Additionally |
| special values "@TIMEOUT_NOTIFICATION_SHORT@", |
| "@TIMEOUT_NOTIFICATION_MIDDLE@", "@TIMEOUT_NOTIFICATION_LONG@" are |
| replaced with standard and translated templates. |
| |
| 6.2.4 Circular Progress Indicator |
| --------------------------------- |
| |
| The circular progress indicator functions similarly to the progress |
| bar. When given an id of "__timeout__", GRUB updates the circular |
| progress indicator's value to indicate the time remaining. For the |
| circular progress indicator, there are two images used to render it: |
| the *center* image, and the *tick* image. The center image is rendered |
| in the center of the component, while the tick image is used to render |
| each mark along the circumference of the indicator. |
| |
| 6.2.5 Labels |
| ------------ |
| |
| Text labels can be placed on the boot screen. The font, color, and |
| horizontal alignment can be specified for labels. If a label is given |
| the id "__timeout__", then the "text" property for that label is also |
| updated with a message informing the user of the number of seconds |
| remaining until automatic boot. This is useful in case you want the |
| text displayed somewhere else instead of directly on the progress bar. |
| |
| 6.2.6 Boot Menu |
| --------------- |
| |
| The boot menu where GRUB displays the menu entries from the "grub.cfg" |
| file. It is a list of items, where each item has a title and an |
| optional icon. The icon is selected based on the *classes* specified |
| for the menu entry. If there is a PNG file named "myclass.png" in the |
| "grub/themes/icons" directory, it will be displayed for items which |
| have the class *myclass*. The boot menu can be customized in several |
| ways, such as the font and color used for the menu entry title, and by |
| specifying styled boxes for the menu itself and for the selected item |
| highlight. |
| |
| 6.2.7 Styled Boxes |
| ------------------ |
| |
| One of the most important features for customizing the layout is the |
| use of *styled boxes*. A styled box is composed of 9 rectangular (and |
| potentially empty) regions, which are used to seamlessly draw the |
| styled box on screen: |
| |
| Northwest (nw) North (n) Northeast (ne) |
| West (w) Center (c) East (e) |
| Southwest (sw) South (s) Southeast (se) |
| |
| 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 fill 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 |
| |
| 6.2.8 Creating Styled Box Images |
| -------------------------------- |
| |
| The Inkscape_ scalable vector graphics editor is a very useful tool for |
| creating styled box images. One process that works well for slicing a |
| drawing into the necessary image slices is: |
| |
| 1. Create or open the drawing you'd like use. |
| |
| 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 you'd like the slices to |
| be. Clear the fill option, and set the stroke to 1 pixel wide |
| solid stroke. The corners of the slices must meet precisely; if |
| it is off by a single pixel, it will probably be evident when the |
| styled box is rendered in the GRUB menu. You should probably go |
| to File | Document Properties | Grids and enable a grid or create |
| a guide (click on one of the rulers next to the drawing and drag |
| over the drawing; release the mouse button to place the guide) to |
| help place the rectangles precisely. |
| |
| 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 files in the same |
| directory as the drawing, named after the slices. These can now |
| be used for a styled box in a GRUB theme. |
| |
| 6.3 Theme File Manual |
| ===================== |
| |
| The theme file is a plain text file. Lines that begin with "#" are |
| ignored and considered comments. (Note: This may not be the case if |
| the previous line ended where a value was expected.) |
| |
| The theme file contains two types of statements: |
| 1. Global properties. |
| |
| 2. Component construction. |
| |
| 6.3.1 Global Properties |
| ----------------------- |
| |
| 6.3.2 Format |
| ------------ |
| |
| Global properties are specified with the simple format: |
| * name1: value1 |
| |
| * name2: "value which may contain spaces" |
| |
| * name3: #88F |
| |
| In this example, name3 is assigned a color value. |
| |
| 6.3.3 Global Property List |
| -------------------------- |
| |
| title-text Specifies the text to display at the top |
| center of the screen as a title. |
| title-font Defines the font used for the title |
| message at the top of the screen. |
| title-color Defines the color of the title message. |
| message-font Defines the font used for messages, such |
| as when GRUB is unable to automatically |
| boot an entry. |
| message-color Defines the color of the message text. |
| message-bg-color Defines the background color of the |
| message text area. |
| desktop-image Specifies the image to use as the |
| background. It will be scaled to fit the |
| screen size. |
| desktop-color Specifies the color for the background if |
| *desktop-image* is not specified. |
| terminal-box Specifies the file name pattern for the |
| styled box slices used for the command |
| line terminal window. For example, |
| "terminal-box: terminal_*.png" will use |
| the images "terminal_c.png" as the center |
| area, "terminal_n.png" as the north (top) |
| edge, "terminal_nw.png" as the northwest |
| (upper left) corner, and so on. If the |
| image for any slice is not found, it will |
| simply be left empty. |
| |
| 6.3.4 Component Construction |
| ---------------------------- |
| |
| Greater customizability comes is provided by components. A tree of |
| components forms the user interface. *Containers* are components that |
| can contain other components, and there is always a single root |
| component which is an instance of a *canvas* container. |
| |
| Components are created in the theme file by prefixing the type of |
| component with a '+' sign: |
| |
| ` + label { text="GRUB" font="aqui 11" color="#8FF" } ' |
| |
| properties of a component are specified as "name = value" (whitespace |
| surrounding tokens is optional and is ignored) where *value* may be: |
| * a single word (e.g., "align = center", "color = #FF8080"), |
| |
| * a quoted string (e.g., "text = "Hello, World!""), or |
| |
| * a tuple (e.g., "preferred_size = (120, 80)"). |
| |
| 6.3.5 Component List |
| -------------------- |
| |
| The following is a list of the components and the properties they |
| support. |
| |
| * label A label displays a line of text. |
| |
| Properties: |
| text The text to display. |
| font The font to use for text display. |
| color The color of the text. |
| align The horizontal alignment of the text within |
| the component. Options are "left", "center", |
| and "right". |
| |
| * image A component that displays an image. The image is scaled |
| to fit the component, although the preferred size defaults to |
| the image's original size unless the "preferred_size" property |
| is explicitly set. |
| |
| Properties: |
| |
| file The full path to the image file to load. |
| |
| * progress_bar Displays a horizontally oriented progress bar. It |
| can be rendered using simple solid filled rectangles, or using |
| a pair of pixmap styled boxes. |
| |
| Properties: |
| |
| fg_color The foreground color for plain solid color |
| rendering. |
| bg_color The background color for plain solid color |
| rendering. |
| border_color The border color for plain solid color |
| rendering. |
| text_color The text color. |
| show_text 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. |
| bar_style The styled box specification for the frame of |
| the progress bar. Example: |
| "progress_frame_*.png" |
| highlight_styleThe styled box specification for the |
| highlighted region of the progress bar. This |
| box will be used to paint just the highlighted |
| region of the bar, and will be increased in |
| size as the bar nears completion. Example: |
| "progress_hl_*.png". |
| text The text to display on the progress bar. If |
| the progress bar's ID is set to "__timeout__", |
| then GRUB will updated this property with an |
| informative message as the timeout approaches. |
| value The progress bar current value. Normally not |
| set manually. |
| start The progress bar start value. Normally not |
| set manually. |
| end The progress bar end value. Normally not set |
| manually. |
| |
| * circular_progress Displays a circular progress indicator. The |
| appearance 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 The file name of the image to draw in |
| the center of the component. |
| tick_bitmap The file name of the image to draw for |
| the tick marks. |
| num_ticks The number of ticks that make up a full |
| circle. |
| ticks_disappear Boolean value indicating whether tick |
| marks should progressively appear, |
| or progressively disappear as *value* |
| approaches *end*. Specify "true" |
| or "false". |
| value The progress indicator current value. |
| Normally not set manually. |
| start The progress indicator start value. |
| Normally not set manually. |
| end 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 The font to use for the menu item |
| titles. |
| selected_item_font The font to use for the selected |
| menu item, or "inherit" (the |
| default) to use "item_font" |
| for the selected menu item as |
| well. |
| item_color The color to use for the menu |
| item titles. |
| selected_item_color The color to use for the selected |
| menu item, or "inherit" (the |
| default) to use |
| "item_color" for the selected |
| menu item as well. |
| icon_width The width of menu item icons. |
| Icons are scaled to the specified |
| size. |
| icon_height The height of menu item icons. |
| item_height The height of each menu item in |
| pixels. |
| item_padding The amount of space in pixels to |
| leave on each side of the menu |
| item contents. |
| item_icon_space The space between an item's icon |
| and the title text, in pixels. |
| item_spacing The amount of space to leave |
| between menu items, in pixels. |
| menu_pixmap_style The image file 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.) |
| selected_item_pixmap_style The image file pattern for the |
| selected item highlight styled |
| box. |
| scrollbar Boolean value indicating whether |
| the scroll bar should be drawn if |
| the frame and thumb styled |
| boxes are configured. |
| scrollbar_frame The image file pattern for the |
| entire scroll bar. |
| Example: "scrollbar_*.png" |
| scrollbar_thumb The image file pattern for the |
| scroll bar thumb (the part of the |
| scroll bar that moves as |
| scrolling occurs). |
| Example: "scrollbar_thumb_*.png" |
| max_items_shown 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. |
| |
| * 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. |
| |
| 6.3.6 Common properties |
| ----------------------- |
| |
| The following properties are supported by all components: |
| `left' |
| The distance from the left border of container to left border of |
| the object in either of three formats: |
| x Value in pixels |
| p% Percentage |
| p%+x mixture of both |
| |
| `top' |
| The distance from the left border of container to left border of |
| the object in same format. |
| |
| `width' |
| The width of object in same format. |
| |
| `height' |
| The height of object in same format. |
| |
| `id' |
| The identifier for the component. This can be any arbitrary |
| string. The ID can be used by scripts to refer to various |
| components in the GUI component tree. Currently, there is one |
| special ID value that GRUB recognizes: |
| |
| "__timeout__" Any component with this ID will have its |
| *text*, *start*, *end*, *value*, and *visible* |
| properties set by GRUB when it is counting |
| down to an automatic boot of the default menu |
| entry. |
| |
| |
| File: grub.info, Node: Network, Next: Serial terminal, Prev: Theme file format, Up: Top |
| |
| 7 Booting GRUB from the network |
| ******************************* |
| |
| 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 pxecmd |
| |
| 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 |
| configuration to offer `grub.pxe' as the boot file (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 files around manually. |
| |
| After GRUB has started, files 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 prefix and in any references to the device name in the |
| configuration file. |
| |
| 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 interface's 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 client's 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 file name provided by DHCP. Read-only. |
| |
| `net_pxe_dhcp_server_name' |
| The name of the DHCP server responsible for these boot parameters. |
| Read-only. |
| |
| `net_default_server' |
| The default server. Read-write, although setting this is only |
| useful before opening a network device. |
| |
| |
| |
| File: grub.info, Node: Serial terminal, Next: Vendor power-on keys, Prev: Network, Up: Top |
| |
| 8 Using GRUB via a serial line |
| ****************************** |
| |
| This chapter describes how to use the serial terminal support in GRUB. |
| |
| If you have many computers or computers with no display/keyboard, it |
| could be very useful to control the computers through serial |
| communications. To connect one computer with another via a serial line, |
| you need to prepare a null-modem (cross) serial cable, and you may need |
| to have multiport serial boards, if your computer doesn't have extra |
| serial ports. In addition, a terminal emulator is also required, such as |
| minicom. Refer to a manual of your operating system, for more |
| information. |
| |
| As for GRUB, the instruction to set up a serial terminal is quite |
| simple. Here is an example: |
| |
| grub> serial --unit=0 --speed=9600 |
| grub> terminal_input serial; terminal_output serial |
| |
| The command `serial' initializes the serial unit 0 with the speed |
| 9600bps. The serial unit 0 is usually called `COM1', so, if you want to |
| use COM2, you must specify `--unit=1' instead. This command accepts |
| many other options, so please refer to *note serial::, for more details. |
| |
| The commands `terminal_input' (*note terminal_input::) and |
| `terminal_output' (*note terminal_output::) choose which type of |
| terminal you want to use. In the case above, the terminal will be a |
| serial terminal, but you can also pass `console' to the command, as |
| `terminal_input serial console'. In this case, a terminal in which you |
| press any key will be selected as a GRUB terminal. In the example above, |
| note that you need to put both commands on the same command line, as you |
| will lose the ability to type commands on the console after the first |
| command. |
| |
| However, note that GRUB assumes that your terminal emulator is |
| compatible with VT100 by default. This is true for most terminal |
| emulators nowadays, but you should pass the option `--dumb' to the |
| command if your terminal emulator is not VT100-compatible or implements |
| few VT100 escape sequences. If you specify this option then GRUB |
| provides you with an alternative menu interface, because the normal |
| menu requires several fancy features of your terminal. |
| |
| |
| File: grub.info, Node: Vendor power-on keys, Next: Images, Prev: Serial terminal, Up: Top |
| |
| 9 Using GRUB with vendor power-on keys |
| ************************************** |
| |
| Some laptop vendors provide an additional power-on button which boots |
| another OS. GRUB supports such buttons with the `GRUB_TIMEOUT_BUTTON', |
| `GRUB_DEFAULT_BUTTON', `GRUB_HIDDEN_TIMEOUT_BUTTON' and |
| `GRUB_BUTTON_CMOS_ADDRESS' variables in default/grub (*note Simple |
| configuration::). `GRUB_TIMEOUT_BUTTON', `GRUB_DEFAULT_BUTTON' and |
| `GRUB_HIDDEN_TIMEOUT_BUTTON' are used instead of the corresponding |
| variables without the `_BUTTON' suffix when powered on using the special |
| button. `GRUB_BUTTON_CMOS_ADDRESS' is vendor-specific and partially |
| model-specific. Values known to the GRUB team are: |
| |
| <Dell XPS M1530> |
| 85:3 |
| |
| <Asus EeePC 1005PE> |
| 84:1 (unconfirmed) |
| |
| To take full advantage of this function, install GRUB into the MBR |
| (*note Installing GRUB using grub-install::). |
| |
| If you have a laptop which has a similar feature and not in the |
| above list could you figure your address and contribute? To discover |
| the address do the following: |
| * boot normally |
| |
| * sudo modprobe nvram |
| sudo cat /dev/nvram | xxd > normal_button.txt |
| |
| * boot using vendor button |
| |
| * sudo modprobe nvram |
| sudo cat /dev/nvram | xxd > normal_vendor.txt |
| |
| Then compare these text files and find where a bit was toggled. E.g. |
| in case of Dell XPS it was: |
| byte 0x47: 20 --> 28 |
| It's a bit number 3 as seen from following table: |
| 0 01 |
| 1 02 |
| 2 04 |
| 3 08 |
| 4 10 |
| 5 20 |
| 6 40 |
| 7 80 |
| |
| 0x47 is decimal 71. Linux nvram implementation cuts first 14 bytes of |
| CMOS. So the real byte address in CMOS is 71+14=85 So complete address |
| is 85:3 |
| |
| |
| File: grub.info, Node: Images, Next: Filesystem, Prev: Vendor power-on keys, Up: Top |
| |
| 10 GRUB image files |
| ******************* |
| |
| GRUB consists of several images: a variety of bootstrap images for |
| starting GRUB in various ways, a kernel image, and a set of modules |
| which are combined with the kernel image to form a core image. Here is |
| a short overview of them. |
| |
| `boot.img' |
| On PC BIOS systems, this image is the first part of GRUB to start. |
| It is written to a master boot record (MBR) or to the boot sector |
| of a partition. Because a PC boot sector is 512 bytes, the size |
| of this image is exactly 512 bytes. |
| |
| The sole function of `boot.img' is to read the first sector of the |
| core image from a local disk and jump to it. Because of the size |
| restriction, `boot.img' cannot understand any file system |
| structure, so `grub-setup' hardcodes the location of the first |
| sector of the core image into `boot.img' when installing GRUB. |
| |
| `diskboot.img' |
| This image is used as the first sector of the core image when |
| booting from a hard disk. It reads the rest of the core image |
| into memory and starts the kernel. Since file system handling is |
| not yet available, it encodes the location of the core image using |
| a block list format. |
| |
| `cdboot.img' |
| This image is used as the first sector of the core image when |
| booting from a CD-ROM drive. It performs a similar function to |
| `diskboot.img'. |
| |
| `pxeboot.img' |
| This image is used as the start of the core image when booting |
| from the network using PXE. *Note Network::. |
| |
| `lnxboot.img' |
| This image may be placed at the start of the core image in order |
| to make GRUB look enough like a Linux kernel that it can be booted |
| by LILO using an `image=' section. |
| |
| `kernel.img' |
| This image contains GRUB's basic run-time facilities: frameworks |
| for device and file handling, environment variables, the rescue |
| mode command-line parser, and so on. It is rarely used directly, |
| but is built into all core images. |
| |
| `core.img' |
| This is the core image of GRUB. It is built dynamically from the |
| kernel image and an arbitrary list of modules by the `grub-mkimage' |
| program. Usually, it contains enough modules to access |
| `/boot/grub', and loads everything else (including menu handling, |
| the ability to load target operating systems, and so on) from the |
| file system at run-time. The modular design allows the core image |
| to be kept small, since the areas of disk where it must be |
| installed are often as small as 32KB. |
| |
| *Note BIOS installation::, for details on where the core image can |
| be installed on PC systems. |
| |
| `*.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 (*note insmod::). |
| |
| For GRUB Legacy users |
| ===================== |
| |
| GRUB 2 has a different design from GRUB Legacy, and so correspondences |
| with the images it used cannot be exact. Nevertheless, GRUB Legacy |
| users often ask questions in the terms they are familiar with, and so |
| here is a brief guide to how GRUB 2's images relate to that. |
| |
| `stage1' |
| Stage 1 from GRUB Legacy was very similar to `boot.img' in GRUB 2, |
| and they serve the same function. |
| |
| `*_stage1_5' |
| In GRUB Legacy, Stage 1.5's function was to include enough |
| filesystem code to allow the much larger Stage 2 to be read from |
| an ordinary filesystem. 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 offers 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 flexible 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 |
| configurations, while GRUB 2 requires `core.img' and cannot work |
| without it. |
| |
| `stage2' |
| GRUB 2 has no single Stage 2 image. Instead, it loads modules from |
| `/boot/grub' at run-time. |
| |
| `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' |
| There is as yet no equivalent for `nbgrub' in GRUB 2; it was used |
| by Etherboot and some other network boot loaders. |
| |
| `pxegrub' |
| 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. *Note Network::. |
| |
| |
| File: grub.info, Node: Filesystem, Next: Interface, Prev: Images, Up: Top |
| |
| 11 Filesystem syntax and semantics |
| ********************************** |
| |
| GRUB uses a special syntax for specifying disk drives which can be |
| accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish |
| between IDE, ESDI, SCSI, or others. You must know yourself which BIOS |
| device is equivalent to which OS device. Normally, that will be clear if |
| you see the files in a device or use the command `search' (*note |
| search::). |
| |
| * Menu: |
| |
| * Device syntax:: How to specify devices |
| * File name syntax:: How to specify files |
| * Block list syntax:: How to specify block lists |
| |
| |
| File: grub.info, Node: Device syntax, Next: File name syntax, Up: Filesystem |
| |
| 11.1 How to specify devices |
| =========================== |
| |
| The device syntax is like this: |
| |
| `(DEVICE[,PARTMAP-NAME1PART-NUM1[,PARTMAP-NAME2PART-NUM2[,...]]])' |
| |
| `[]' means the parameter is optional. DEVICE depends on the disk |
| driver in use. BIOS and EFI disks use either `fd' or `hd' followed by a |
| digit, like `fd0', or `cd'. AHCI, PATA (ata), crypto, USB use the name |
| of driver followed by a number. Memdisk and host are limited to one |
| disk and so it's refered just by driver name. RAID (md), ofdisk |
| (ieee1275 and nand), LVM (lv), LDM and arcdisk (arc) use intrinsic name |
| of disk prefixed by driver name. Additionally just "nand" refers to the |
| disk aliased as "nand". Conflicts are solved by suffixing a number if |
| necessarry. Commas need to be escaped. Loopback uses whatever name |
| specified to `loopback' command. Hostdisk uses names specified in |
| device.map as long as it's of the form [fhc]d[0-9]* or hostdisk/<OS |
| DEVICE>. For crypto and RAID (md) additionally you can use the syntax |
| <driver name>uuid/<uuid>. |
| |
| (fd0) |
| (hd0) |
| (cd) |
| (ahci0) |
| (ata0) |
| (crypto0) |
| (usb0) |
| (cryptouuid/123456789abcdef0123456789abcdef0) |
| (mduuid/123456789abcdef0123456789abcdef0) |
| (lv/system-root) |
| (md/myraid) |
| (md/0) |
| (ieee1275/disk2) |
| (ieee1275//pci@1f\,0/ide@d/disk@2) |
| (nand) |
| (memdisk) |
| (host) |
| (myloop) |
| (hostdisk//dev/sda) |
| |
| PART-NUM represents the partition number of DEVICE, starting from |
| one. PARTNAME is optional but is recommended since disk may have |
| several top-level partmaps. Specifying third and later component you |
| can access to subpartitions. |
| |
| The syntax `(hd0)' represents using the entire disk (or the MBR when |
| installing GRUB), while the syntax `(hd0,1)' represents using the first |
| partition of the disk (or the boot sector of the partition when |
| installing GRUB). |
| |
| (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. *Note Network::, for more information. |
| |
| If you boot GRUB from a CD-ROM, `(cd)' is available. *Note Making a |
| GRUB bootable CD-ROM::, for details. |
| |
| |
| File: grub.info, Node: File name syntax, Next: Block list syntax, Prev: Device syntax, Up: Filesystem |
| |
| 11.2 How to specify files |
| ========================= |
| |
| There are two ways to specify files, by "absolute file name" and by |
| "block list". |
| |
| An absolute file name resembles a Unix absolute file name, using `/' |
| for the directory separator (not `\' as in DOS). One example is |
| `(hd0,1)/boot/grub/grub.cfg'. This means the file `/boot/grub/grub.cfg' |
| in the first partition of the first hard disk. If you omit the device |
| name in an absolute file name, GRUB uses GRUB's "root device" |
| implicitly. So if you set the root device to, say, `(hd1,1)' by the |
| command `set root=(hd1,1)' (*note set::), then `/boot/kernel' is the |
| same as `(hd1,1)/boot/kernel'. |
| |
| |
| File: grub.info, Node: Block list syntax, Prev: File name syntax, Up: Filesystem |
| |
| 11.3 How to specify block lists |
| =============================== |
| |
| A block list is used for specifying a file that doesn't appear in the |
| filesystem, like a chainloader. The syntax is |
| `[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'. Here is an example: |
| |
| `0+100,200+1,300+300' |
| |
| This represents that GRUB should read blocks 0 through 99, block 200, |
| and blocks 300 through 599. If you omit an offset, then GRUB assumes |
| the offset is zero. |
| |
| Like the file name syntax (*note File name syntax::), if a blocklist |
| does not contain a device name, then GRUB uses GRUB's "root device". So |
| `(hd0,2)+1' is the same as `+1' when the root device is `(hd0,2)'. |
| |
| |
| File: grub.info, Node: Interface, Next: Environment, Prev: Filesystem, Up: Top |
| |
| 12 GRUB's user interface |
| ************************ |
| |
| GRUB has both a simple menu interface for choosing preset entries from a |
| configuration file, and a highly flexible command-line for performing |
| any desired combination of boot commands. |
| |
| GRUB looks for its configuration file as soon as it is loaded. If one |
| is found, then the full menu interface is activated using whatever |
| entries were found in the file. If you choose the "command-line" menu |
| option, or if the configuration file was not found, then GRUB drops to |
| the command-line interface. |
| |
| * Menu: |
| |
| * Command-line interface:: The flexible command-line interface |
| * Menu interface:: The simple menu interface |
| * Menu entry editor:: Editing a menu entry |
| |
| |
| File: grub.info, Node: Command-line interface, Next: Menu interface, Up: Interface |
| |
| 12.1 The flexible command-line interface |
| ======================================== |
| |
| The command-line interface provides a prompt and after it an editable |
| text area much like a command-line in Unix or DOS. Each command is |
| immediately executed after it is entered(1) (*note Command-line |
| interface-Footnote-1::). The commands (*note Command-line and menu |
| entry commands::) are a subset of those available in the configuration |
| file, used with exactly the same syntax. |
| |
| Cursor movement and editing of the text on the line can be done via a |
| subset of the functions available in the Bash shell: |
| |
| <C-f> |
| <PC right key> |
| Move forward one character. |
| |
| <C-b> |
| <PC left key> |
| Move back one character. |
| |
| <C-a> |
| <HOME> |
| Move to the start of the line. |
| |
| <C-e> |
| <END> |
| Move the the end of the line. |
| |
| <C-d> |
| <DEL> |
| Delete the character underneath the cursor. |
| |
| <C-h> |
| <BS> |
| Delete the character to the left of the cursor. |
| |
| <C-k> |
| Kill the text from the current cursor position to the end of the |
| line. |
| |
| <C-u> |
| Kill backward from the cursor to the beginning of the line. |
| |
| <C-y> |
| Yank the killed text back into the buffer at the cursor. |
| |
| <C-p> |
| <PC up key> |
| Move up through the history list. |
| |
| <C-n> |
| <PC down key> |
| Move down through the history list. |
| |
| When typing commands interactively, if the cursor is within or before |
| the first 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 first word, the `<TAB>' will provide a completion listing of |
| disks, partitions, and file 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 |
| filesystem. This is because TFTP doesn't support file name listing for |
| the security. |
| |
| |
| File: grub.info, Node: Command-line interface-Footnotes, Up: Command-line interface |
| |
| (1) However, this behavior will be changed in the future version, in |
| a user-invisible way. |
| |
| |
| File: grub.info, Node: Menu interface, Next: Menu entry editor, Prev: Command-line interface, Up: Interface |
| |
| 12.2 The simple menu interface |
| ============================== |
| |
| The menu interface is quite easy to use. Its commands are both |
| reasonably intuitive and described on screen. |
| |
| Basically, the menu interface provides a list of "boot entries" to |
| the user to choose from. Use the arrow keys to select the entry of |
| choice, then press <RET> to run it. An optional timeout is available |
| to boot the default entry (the first one if not set), which is aborted |
| by pressing any key. |
| |
| Commands are available to enter a bare command-line by pressing <c> |
| (which operates exactly like the non-config-file version of GRUB, but |
| allows one to return to the menu if desired by pressing <ESC>) or to |
| edit any of the "boot entries" by pressing <e>. |
| |
| If you protect the menu interface with a password (*note Security::), |
| all you can do is choose an entry by pressing <RET>, or press <p> to |
| enter the password. |
| |
| |
| File: grub.info, Node: Menu entry editor, Prev: Menu interface, Up: Interface |
| |
| 12.3 Editing a menu entry |
| ========================= |
| |
| The menu entry editor looks much like the main menu interface, but the |
| lines in the menu are individual commands in the selected entry instead |
| of entry names. |
| |
| If an <ESC> is pressed in the editor, it aborts all the changes made |
| to the configuration entry and returns to the main menu interface. |
| |
| Each line in the menu entry can be edited freely, and you can add |
| new lines by pressing <RET> at the end of a line. To boot the edited |
| entry, press <Ctrl-x>. |
| |
| Although GRUB unfortunately does not support "undo", you can do |
| almost the same thing by just returning to the main menu using <ESC>. |
| |
| |
| File: grub.info, Node: Environment, Next: Commands, Prev: Interface, Up: Top |
| |
| 13 GRUB environment variables |
| ***************************** |
| |
| GRUB supports environment variables which are rather like those offered |
| by all Unix-like systems. Environment variables have a name, which is |
| unique and is usually a short identifier, and a value, which is an |
| arbitrary string of characters. They may be set (*note set::), unset |
| (*note unset::), or looked up (*note Shell-like scripting::) by name. |
| |
| A number of environment variables have special meanings to various |
| parts of GRUB. Others may be used freely in GRUB configuration files. |
| |
| * Menu: |
| |
| * Special environment variables:: |
| * Environment block:: |
| |
| |
| File: grub.info, Node: Special environment variables, Next: Environment block, Up: Environment |
| |
| 13.1 Special environment variables |
| ================================== |
| |
| These variables have special meaning to GRUB. |
| |
| * Menu: |
| |
| * biosnum:: |
| * chosen:: |
| * color_highlight:: |
| * color_normal:: |
| * debug:: |
| * default:: |
| * fallback:: |
| * gfxmode:: |
| * gfxpayload:: |
| * gfxterm_font:: |
| * icondir:: |
| * lang:: |
| * locale_dir:: |
| * menu_color_highlight:: |
| * menu_color_normal:: |
| * net_pxe_boot_file:: |
| * net_pxe_dhcp_server_name:: |
| * net_pxe_domain:: |
| * net_pxe_extensionspath:: |
| * net_pxe_hostname:: |
| * net_pxe_ip:: |
| * net_pxe_mac:: |
| * net_pxe_rootpath:: |
| * pager:: |
| * prefix:: |
| * pxe_blksize:: |
| * pxe_default_gateway:: |
| * pxe_default_server:: |
| * root:: |
| * superusers:: |
| * theme:: |
| * timeout:: |
| |
| |
| File: grub.info, Node: biosnum, Next: chosen, Up: Special environment variables |
| |
| 13.1.1 biosnum |
| -------------- |
| |
| When chain-loading another boot loader (*note Chain-loading::), GRUB may |
| need to know what BIOS drive number corresponds to the root device |
| (*note root::) so that it can set up registers properly. If the |
| BIOSNUM variable is set, it overrides GRUB's own means of guessing this. |
| |
| For an alternative approach which also changes BIOS drive mappings |
| for the chain-loaded system, *note drivemap::. |
| |
| |
| File: grub.info, Node: chosen, Next: color_highlight, Prev: biosnum, Up: Special environment variables |
| |
| 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 `>'. |
| |
| |
| File: grub.info, Node: color_highlight, Next: color_normal, Prev: chosen, Up: Special environment variables |
| |
| 13.1.3 color_highlight |
| ---------------------- |
| |
| This variable contains the "highlight" foreground and background |
| terminal colors, separated by a slash (`/'). Setting this variable |
| changes those colors. For the available color names, *note |
| color_normal::. |
| |
| The default is `black/white'. |
| |
| |
| File: grub.info, Node: color_normal, Next: debug, Prev: color_highlight, Up: Special environment variables |
| |
| 13.1.4 color_normal |
| ------------------- |
| |
| This variable contains the "normal" foreground and background terminal |
| colors, separated by a slash (`/'). Setting this variable changes |
| those colors. Each color must be a name from the following list: |
| |
| * black |
| |
| * blue |
| |
| * green |
| |
| * cyan |
| |
| * red |
| |
| * magenta |
| |
| * brown |
| |
| * light-gray |
| |
| * dark-gray |
| |
| * light-blue |
| |
| * light-green |
| |
| * light-cyan |
| |
| * light-red |
| |
| * light-magenta |
| |
| * yellow |
| |
| * white |
| |
| The default is `white/black'. |
| |
| |
| File: grub.info, Node: debug, Next: default, Prev: color_normal, Up: Special environment variables |
| |
| 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. |
| |
| |
| File: grub.info, Node: default, Next: fallback, Prev: debug, Up: Special environment variables |
| |
| 13.1.6 default |
| -------------- |
| |
| If this variable is set, it identifies a menu entry that should be |
| selected by default, possibly after a timeout (*note timeout::). The |
| entry may be identified by number or by title. |
| |
| If the entry is in a submenu, then it must be identified 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 identified as `Submenu 2>Submenu 3>Menu |
| Entry 3'. |
| |
| This variable is often set by `GRUB_DEFAULT' (*note Simple |
| configuration::), `grub-set-default', or `grub-reboot'. |
| |
| |
| File: grub.info, Node: fallback, Next: gfxmode, Prev: default, Up: Special environment variables |
| |
| 13.1.7 fallback |
| --------------- |
| |
| If this variable is set, it identifies a menu entry that should be |
| selected if the default menu entry fails to boot. Entries are |
| identified in the same way as for `default' (*note default::). |
| |
| |
| File: grub.info, Node: gfxmode, Next: gfxpayload, Prev: fallback, Up: Special environment variables |
| |
| 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-specific default that should look |
| reasonable. |
| |
| The resolution may be specified 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', |
| `WIDTHxHEIGHT', or `WIDTHxHEIGHTxDEPTH'. |
| |
| |
| File: grub.info, Node: gfxpayload, Next: gfxterm_font, Prev: gfxmode, Up: Special environment variables |
| |
| 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 (*note linux::). 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 |
| (*note gfxmode::). |
| |
| Depending on your kernel, your distribution, your graphics card, and |
| the phase of the moon, note that using this option may cause GNU/Linux |
| to suffer from various display problems, particularly during the early |
| part of the 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-specific. On platforms with a native text |
| mode (such as PC BIOS platforms), the default is `text'. Otherwise the |
| default may be `auto' or a specific video mode. |
| |
| This variable is often set by `GRUB_GFXPAYLOAD_LINUX' (*note Simple |
| configuration::). |
| |
| |
| File: grub.info, Node: gfxterm_font, Next: icondir, Prev: gfxpayload, Up: Special environment variables |
| |
| 13.1.10 gfxterm_font |
| -------------------- |
| |
| If this variable is set, it names a font to use for text on the |
| `gfxterm' graphical terminal. Otherwise, `gfxterm' may use any |
| available font. |
| |
| |
| File: grub.info, Node: icondir, Next: lang, Prev: gfxterm_font, Up: Special environment variables |
| |
| 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 theme's |
| `icons' directory. *Note Theme file format::. |
| |
| |
| File: grub.info, Node: lang, Next: locale_dir, Prev: icondir, Up: Special environment variables |
| |
| 13.1.12 lang |
| ------------ |
| |
| If this variable is set, it names the language code that the `gettext' |
| command (*note gettext::) uses to translate strings. For example, |
| French would be named as `fr', and Simplified Chinese as `zh_CN'. |
| |
| `grub-mkconfig' (*note Simple configuration::) will try to set a |
| reasonable default for this variable based on the system locale. |
| |
| |
| File: grub.info, Node: locale_dir, Next: menu_color_highlight, Prev: lang, Up: Special environment variables |
| |
| 13.1.13 locale_dir |
| ------------------ |
| |
| If this variable is set, it names the directory where translation files |
| may be found (*note gettext::), usually `/boot/grub/locale'. Otherwise, |
| internationalization is disabled. |
| |
| `grub-mkconfig' (*note Simple configuration::) will set a reasonable |
| default for this variable if internationalization is needed and any |
| translation files are available. |
| |
| |
| File: grub.info, Node: menu_color_highlight, Next: menu_color_normal, Prev: locale_dir, Up: Special environment variables |
| |
| 13.1.14 menu_color_highlight |
| ---------------------------- |
| |
| This variable contains the foreground and background colors to be used |
| for the highlighted menu entry, separated by a slash (`/'). Setting |
| this variable changes those colors. For the available color names, |
| *note color_normal::. |
| |
| The default is the value of `color_highlight' (*note |
| color_highlight::). |
| |
| |
| File: grub.info, Node: menu_color_normal, Next: net_pxe_boot_file, Prev: menu_color_highlight, Up: Special environment variables |
| |
| 13.1.15 menu_color_normal |
| ------------------------- |
| |
| This variable contains the foreground and background colors to be used |
| for non-highlighted menu entries, separated by a slash (`/'). Setting |
| this variable changes those colors. For the available color names, |
| *note color_normal::. |
| |
| The default is the value of `color_normal' (*note color_normal::). |
| |
| |
| File: grub.info, Node: net_pxe_boot_file, Next: net_pxe_dhcp_server_name, Prev: menu_color_normal, Up: Special environment variables |
| |
| 13.1.16 net_pxe_boot_file |
| ------------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_dhcp_server_name, Next: net_pxe_domain, Prev: net_pxe_boot_file, Up: Special environment variables |
| |
| 13.1.17 net_pxe_dhcp_server_name |
| -------------------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_domain, Next: net_pxe_extensionspath, Prev: net_pxe_dhcp_server_name, Up: Special environment variables |
| |
| 13.1.18 net_pxe_domain |
| ---------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_extensionspath, Next: net_pxe_hostname, Prev: net_pxe_domain, Up: Special environment variables |
| |
| 13.1.19 net_pxe_extensionspath |
| ------------------------------ |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_hostname, Next: net_pxe_ip, Prev: net_pxe_extensionspath, Up: Special environment variables |
| |
| 13.1.20 net_pxe_hostname |
| ------------------------ |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_ip, Next: net_pxe_mac, Prev: net_pxe_hostname, Up: Special environment variables |
| |
| 13.1.21 net_pxe_ip |
| ------------------ |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_mac, Next: net_pxe_rootpath, Prev: net_pxe_ip, Up: Special environment variables |
| |
| 13.1.22 net_pxe_mac |
| ------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: net_pxe_rootpath, Next: pager, Prev: net_pxe_mac, Up: Special environment variables |
| |
| 13.1.23 net_pxe_rootpath |
| ------------------------ |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: pager, Next: prefix, Prev: net_pxe_rootpath, Up: Special environment variables |
| |
| 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. |
| |
| |
| File: grub.info, Node: prefix, Next: pxe_blksize, Prev: pager, Up: Special environment variables |
| |
| 13.1.25 prefix |
| -------------- |
| |
| The location of the `/boot/grub' directory as an absolute file name |
| (*note File name syntax::). 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. |
| |
| |
| File: grub.info, Node: pxe_blksize, Next: pxe_default_gateway, Prev: prefix, Up: Special environment variables |
| |
| 13.1.26 pxe_blksize |
| ------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: pxe_default_gateway, Next: pxe_default_server, Prev: pxe_blksize, Up: Special environment variables |
| |
| 13.1.27 pxe_default_gateway |
| --------------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: pxe_default_server, Next: root, Prev: pxe_default_gateway, Up: Special environment variables |
| |
| 13.1.28 pxe_default_server |
| -------------------------- |
| |
| *Note Network::. |
| |
| |
| File: grub.info, Node: root, Next: superusers, Prev: pxe_default_server, Up: Special environment variables |
| |
| 13.1.29 root |
| ------------ |
| |
| The root device name (*note Device syntax::). Any file 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' (*note prefix::). |
| |
| For example, if GRUB was installed to the first partition of the |
| first hard disk, then `prefix' might be set to `(hd0,msdos1)/boot/grub' |
| and `root' to `hd0,msdos1'. |
| |
| |
| File: grub.info, Node: superusers, Next: theme, Prev: root, Up: Special environment variables |
| |
| 13.1.30 superusers |
| ------------------ |
| |
| This variable may be set to a list of superuser names to enable |
| authentication support. *Note Security::. |
| |
| |
| File: grub.info, Node: theme, Next: timeout, Prev: superusers, Up: Special environment variables |
| |
| 13.1.31 theme |
| ------------- |
| |
| This variable may be set to a directory containing a GRUB graphical menu |
| theme. *Note Theme file format::. |
| |
| This variable is often set by `GRUB_THEME' (*note Simple |
| configuration::). |
| |
| |
| File: grub.info, Node: timeout, Prev: theme, Up: Special environment variables |
| |
| 13.1.32 timeout |
| --------------- |
| |
| If this variable is set, it specifies 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 indefinitely. |
| |
| This variable is often set by `GRUB_TIMEOUT' or |
| `GRUB_HIDDEN_TIMEOUT' (*note Simple configuration::). |
| |
| |
| File: grub.info, Node: Environment block, Prev: Special environment variables, Up: Environment |
| |
| 13.2 The GRUB environment block |
| =============================== |
| |
| It is often useful to be able to remember a small amount of information |
| from one boot to the next. For example, you might want to set the |
| default menu entry based on what was selected the last time. GRUB |
| deliberately does not implement support for writing files in order to |
| minimise the possibility of the boot loader being responsible for file |
| system corruption, so a GRUB configuration file cannot just create a |
| file 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 file, which |
| normally lives in `/boot/grub/grubenv' (although you should not assume |
| this). At boot time, the `load_env' command (*note load_env::) loads |
| environment variables from it, and the `save_env' (*note save_env::) |
| 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 filesystem (no |
| ZFS), and using BIOS or EFI functions (no ATA, USB or IEEE1275). |
| |
| `grub-mkconfig' uses this facility to implement `GRUB_SAVEDEFAULT' |
| (*note Simple configuration::). |
| |
| |
| File: grub.info, Node: Commands, Next: Internationalisation, Prev: Environment, Up: Top |
| |
| 14 The list of available commands |
| ********************************* |
| |
| In this chapter, we list all commands that are available in GRUB. |
| |
| Commands belong to different groups. A few can only be used in the |
| global section of the configuration file (or "menu"); most of them can |
| be entered on the command-line and can be used either anywhere in the |
| menu or specifically in the menu entries. |
| |
| In rescue mode, only the `insmod' (*note insmod::), `ls' (*note |
| ls::), `set' (*note set::), and `unset' (*note unset::) commands are |
| normally available. If you end up in rescue mode and do not know what |
| to do, then *note GRUB only offers a rescue shell::. |
| |
| * Menu: |
| |
| * Menu-specific commands:: |
| * General commands:: |
| * Command-line and menu entry commands:: |
| |
| |
| File: grub.info, Node: Menu-specific commands, Next: General commands, Up: Commands |
| |
| 14.1 The list of commands for the menu only |
| =========================================== |
| |
| The semantics used in parsing the configuration file are the following: |
| |
| * The files _must_ be in plain-text format. |
| |
| * `#' at the beginning of a line in a configuration file means it is |
| only a comment. |
| |
| * Options are separated by spaces. |
| |
| * All numbers can be either decimal or hexadecimal. A hexadecimal |
| number must be preceded by `0x', and is case-insensitive. |
| |
| These commands can only be used in the menu: |
| |
| * Menu: |
| |
| * menuentry:: Start a menu entry |
| * submenu:: Group menu entries |
| |
| |
| File: grub.info, Node: menuentry, Next: submenu, Up: Menu-specific commands |
| |
| 14.1.1 menuentry |
| ---------------- |
| |
| -- Command: menuentry TITLE [`--class=class' ...] [`--users=users'] |
| [`--unrestricted'] [`--hotkey=key'] { COMMAND; ... } |
| This defines 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 different classes |
| using different styles. |
| |
| The `--users' option grants specific users access to specific menu |
| entries. *Note Security::. |
| |
| The `--unrestricted' option grants all users access to specific |
| menu entries. *Note Security::. |
| |
| 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'. |
| |
| |
| File: grub.info, Node: submenu, Prev: menuentry, Up: Menu-specific commands |
| |
| 14.1.2 submenu |
| -------------- |
| |
| -- Command: submenu TITLE [`--class=class' ...] [`--users=users'] |
| [`--unrestricted'] [`--hotkey=key'] { MENU ENTRIES ... } |
| This defines 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. |
| |
| All options are the same as in the `menuentry' command (*note |
| menuentry::). |
| |
| |
| File: grub.info, Node: General commands, Next: Command-line and menu entry commands, Prev: Menu-specific commands, Up: Commands |
| |
| 14.2 The list of general commands |
| ================================= |
| |
| Commands usable anywhere in the menu and in the command-line. |
| |
| * Menu: |
| |
| * serial:: Set up a serial device |
| * terminal_input:: Manage input terminals |
| * terminal_output:: Manage output terminals |
| * terminfo:: Define terminal type |
| |
| |
| File: grub.info, Node: serial, Next: terminal_input, Up: General commands |
| |
| 14.2.1 serial |
| ------------- |
| |
| -- Command: serial [`--unit=unit'] [`--port=port'] [`--speed=speed'] |
| [`--word=word'] [`--parity=parity'] [`--stop=stop'] |
| Initialize a serial device. UNIT is a number in the range 0-3 |
| 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 specified 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 (*note |
| terminal_input::, *note terminal_output::). |
| |
| See also *note Serial terminal::. |
| |
| |
| File: grub.info, Node: terminal_input, Next: terminal_output, Prev: serial, Up: General commands |
| |
| 14.2.2 terminal_input |
| --------------------- |
| |
| -- Command: terminal_input [`--append'|`--remove'] [terminal1] |
| [terminal2] ... |
| List or select an input terminal. |
| |
| With no arguments, list the active and available input terminals. |
| |
| With `--append', add the named terminals to the list of active |
| input terminals; any of these may be used to provide input to GRUB. |
| |
| With `--remove', remove the named terminals from the active list. |
| |
| With no options but a list of terminal names, make only the listed |
| terminal names active. |
| |
| |
| File: grub.info, Node: terminal_output, Next: terminfo, Prev: terminal_input, Up: General commands |
| |
| 14.2.3 terminal_output |
| ---------------------- |
| |
| -- Command: terminal_output [`--append'|`--remove'] [terminal1] |
| [terminal2] ... |
| List or select an output terminal. |
| |
| With no arguments, list the active and available output terminals. |
| |
| With `--append', add the named terminals to the list of active |
| output terminals; all of these will receive output from GRUB. |
| |
| With `--remove', remove the named terminals from the active list. |
| |
| With no options but a list of terminal names, make only the listed |
| terminal names active. |
| |
| |
| File: grub.info, Node: terminfo, Prev: terminal_output, Up: General commands |
| |
| 14.2.4 terminfo |
| --------------- |
| |
| -- Command: terminfo [-a|-u|-v] [term] |
| Define 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' specifies |
| an ASCII-only terminal; `-u' specifies logically-ordered UTF-8; |
| and `-v' specifies "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 specified, the current terminal |
| type is printed. |
| |
| |
| File: grub.info, Node: Command-line and menu entry commands, Prev: General commands, Up: Commands |
| |
| 14.3 The list of command-line and menu entry commands |
| ===================================================== |
| |
| These commands are usable in the command-line and in menu entries. If |
| you forget a command, you can run the command `help' (*note help::). |
| |
| * Menu: |
| |
| * acpi:: Load ACPI tables |
| * badram:: Filter out bad regions of RAM |
| * blocklist:: Print a block list |
| * boot:: Start up your operating system |
| * cat:: Show the contents of a file |
| * chainloader:: Chain-load another boot loader |
| * cmp:: Compare two files |
| * configfile:: Load a configuration file |
| * cpuid:: Check for CPU features |
| * crc:: Calculate CRC32 checksums |
| * date:: Display or set current date and time |
| * drivemap:: Map a drive to another |
| * echo:: Display a line of text |
| * export:: Export an environment variable |
| * false:: Do nothing, unsuccessfully |
| * gettext:: Translate a string |
| * gptsync:: Fill an MBR based on GPT entries |
| * halt:: Shut down your computer |
| * help:: Show help messages |
| * initrd:: Load a Linux initrd |
| * initrd16:: Load a Linux initrd (16-bit mode) |
| * insmod:: Insert a module |
| * keystatus:: Check key modifier status |
| * linux:: Load a Linux kernel |
| * linux16:: Load a Linux kernel (16-bit mode) |
| * list_env:: List variables in environment block |
| * load_env:: Load variables from environment block |
| * loopback:: Make a device from a filesystem image |
| * ls:: List devices or files |
| * normal:: Enter normal mode |
| * normal_exit:: Exit from normal mode |
| * parttool:: Modify partition table entries |
| * password:: Set a clear-text password |
| * password_pbkdf2:: Set a hashed password |
| * play:: Play a tune |
| * pxe_unload:: Unload the PXE environment |
| * read:: Read user input |
| * reboot:: Reboot your computer |
| * save_env:: Save variables to environment block |
| * search:: Search devices by file, label, or UUID |
| * sendkey:: Emulate keystrokes |
| * set:: Set an environment variable |
| * true:: Do nothing, successfully |
| * unset:: Unset an environment variable |
| * uppermem:: Set the upper memory size |
| |
| |
| File: grub.info, Node: acpi, Next: badram, Up: Command-line and menu entry commands |
| |
| 14.3.1 acpi |
| ----------- |
| |
| -- Command: acpi [`-1'|`-2'] |
| [`--exclude=table1,...'|`--load-only=table1,...'] |
| [`--oemid=id'] [`--oemtable=table'] [`--oemtablerev=rev'] |
| [`--oemtablecreator=creator'] [`--oemtablecreatorrev=rev'] |
| [`--no-ebda'] filename ... |
| Modern BIOS systems normally implement the Advanced Configuration |
| and Power Interface (ACPI), and define various tables that |
| describe the interface between an ACPI-compliant operating system |
| and the firmware. 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 GRUB's EFI emulation. |
| |
| |
| File: grub.info, Node: badram, Next: blocklist, Prev: acpi, Up: Command-line and menu entry commands |
| |
| 14.3.2 badram |
| ------------- |
| |
| -- Command: badram addr,mask[,addr,mask...] |
| Filter out bad RAM. |
| |
| This command notifies the memory manager that specified regions of |
| RAM ought to be filtered out (usually, because they're damaged). This |
| remains in effect 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. |
| |
| Syntax is the same as provided by the Memtest86+ utility |
| (http://www.memtest.org/): 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 filtered. This syntax makes |
| it easy to represent patterns that are often result of memory damage, |
| due to physical distribution of memory cells. |
| |
| |
| File: grub.info, Node: blocklist, Next: boot, Prev: badram, Up: Command-line and menu entry commands |
| |
| 14.3.3 blocklist |
| ---------------- |
| |
| -- Command: blocklist file |
| Print a block list (*note Block list syntax::) for FILE. |
| |
| |
| File: grub.info, Node: boot, Next: cat, Prev: blocklist, Up: Command-line and menu entry commands |
| |
| 14.3.4 boot |
| ----------- |
| |
| -- Command: boot |
| 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). |
| |
| |
| File: grub.info, Node: cat, Next: chainloader, Prev: boot, Up: Command-line and menu entry commands |
| |
| 14.3.5 cat |
| ---------- |
| |
| -- Command: cat [`--dos'] file |
| Display the contents of the file FILE. This command may be useful |
| to remind you of your OS's 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 file |
| formatted using DOS-style line endings. |
| |
| |
| File: grub.info, Node: chainloader, Next: cmp, Prev: cat, Up: Command-line and menu entry commands |
| |
| 14.3.6 chainloader |
| ------------------ |
| |
| -- Command: chainloader [`--force'] file |
| Load FILE as a chain-loader. Like any other file loaded by the |
| filesystem code, it can use the blocklist notation (*note Block |
| list syntax::) to grab the first sector of the current partition |
| with `+1'. If you specify the option `--force', then load FILE |
| 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. |
| |
| |
| File: grub.info, Node: cmp, Next: configfile, Prev: chainloader, Up: Command-line and menu entry commands |
| |
| 14.3.7 cmp |
| ---------- |
| |
| -- Command: cmp file1 file2 |
| Compare the file FILE1 with the file FILE2. If they differ in |
| size, print the sizes like this: |
| |
| Differ in size: 0x1234 [foo], 0x4321 [bar] |
| |
| If the sizes are equal but the bytes at an offset differ, then |
| print the bytes like this: |
| |
| Differ at the offset 777: 0xbe [foo], 0xef [bar] |
| |
| If they are completely identical, nothing will be printed. |
| |
| |
| File: grub.info, Node: configfile, Next: cpuid, Prev: cmp, Up: Command-line and menu entry commands |
| |
| 14.3.8 configfile |
| ----------------- |
| |
| -- Command: configfile file |
| Load FILE as a configuration file. If FILE defines any menu |
| entries, then show a menu containing them immediately. |
| |
| |
| File: grub.info, Node: cpuid, Next: crc, Prev: configfile, Up: Command-line and menu entry commands |
| |
| 14.3.9 cpuid |
| ------------ |
| |
| -- Command: cpuid [-l] |
| 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. |
| |
| |
| File: grub.info, Node: crc, Next: date, Prev: cpuid, Up: Command-line and menu entry commands |
| |
| 14.3.10 crc |
| ----------- |
| |
| -- Command: crc file |
| Display the CRC32 checksum of FILE. |
| |
| |
| File: grub.info, Node: date, Next: drivemap, Prev: crc, Up: Command-line and menu entry commands |
| |
| 14.3.11 date |
| ------------ |
| |
| -- Command: date [[year-]month-day] [hour:minute[:second]] |
| With no arguments, print the current date and time. |
| |
| Otherwise, take the current date and time, change any elements |
| specified 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. |
| |
| |
| File: grub.info, Node: drivemap, Next: echo, Prev: date, Up: Command-line and menu entry commands |
| |
| 14.3.12 drivemap |
| ---------------- |
| |
| -- Command: drivemap `-l'|`-r'|[`-s'] from_drive to_drive |
| 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-first drive. For |
| convenience, any partition suffix on the drive is ignored, so you |
| can safely use ${root} as a drive specification. |
| |
| 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) |
| |
| |
| File: grub.info, Node: echo, Next: export, Prev: drivemap, Up: Command-line and menu entry commands |
| |
| 14.3.13 echo |
| ------------ |
| |
| -- Command: echo [`-n'] [`-e'] string ... |
| 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}'. |
| |
| The `-e' option enables interpretation of backslash escapes. The |
| following sequences are recognised: |
| |
| `\\' |
| backslash |
| |
| `\a' |
| alert (BEL) |
| |
| `\c' |
| suppress trailing new line |
| |
| `\f' |
| form feed |
| |
| `\n' |
| new line |
| |
| `\r' |
| carriage return |
| |
| `\t' |
| horizontal tab |
| |
| `\v' |
| vertical tab |
| |
| When interpreting backslash escapes, backslash followed by any |
| other character will print that character. |
| |
| |
| File: grub.info, Node: export, Next: false, Prev: echo, Up: Command-line and menu entry commands |
| |
| 14.3.14 export |
| -------------- |
| |
| -- Command: export envvar |
| Export the environment variable ENVVAR. Exported variables are |
| visible to subsidiary configuration files loaded using |
| `configfile'. |
| |
| |
| File: grub.info, Node: false, Next: gettext, Prev: export, Up: Command-line and menu entry commands |
| |
| 14.3.15 false |
| ------------- |
| |
| -- Command: false |
| Do nothing, unsuccessfully. This is mainly useful in control |
| constructs such as `if' and `while' (*note Shell-like scripting::). |
| |
| |
| File: grub.info, Node: gettext, Next: gptsync, Prev: false, Up: Command-line and menu entry commands |
| |
| 14.3.16 gettext |
| --------------- |
| |
| -- Command: gettext string |
| Translate STRING into the current language. |
| |
| The current language code is stored in the `lang' variable in |
| GRUB's environment (*note lang::). Translation files in MO format |
| are read from `locale_dir' (*note locale_dir::), usually |
| `/boot/grub/locale'. |
| |
| |
| File: grub.info, Node: gptsync, Next: halt, Prev: gettext, Up: Command-line and menu entry commands |
| |
| 14.3.17 gptsync |
| --------------- |
| |
| -- Command: gptsync device [partition[+/-[type]]] ... |
| Disks using the GUID Partition Table (GPT) also have a legacy |
| Master Boot Record (MBR) partition table 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 specified PARTITION |
| entries on DEVICE. Up to three partitions may be used. |
| |
| TYPE is an MBR partition type code; prefix 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. |
| |
| |
| File: grub.info, Node: halt, Next: help, Prev: gptsync, Up: Command-line and menu entry commands |
| |
| 14.3.18 halt |
| ------------ |
| |
| -- Command: halt `--no-apm' |
| The command halts the computer. If the `--no-apm' option is |
| specified, no APM BIOS call is performed. Otherwise, the computer |
| is shut down using APM. |
| |
| |
| File: grub.info, Node: help, Next: initrd, Prev: halt, Up: Command-line and menu entry commands |
| |
| 14.3.19 help |
| ------------ |
| |
| -- Command: help [pattern ...] |
| 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. |
| |
| |
| File: grub.info, Node: initrd, Next: initrd16, Prev: help, Up: Command-line and menu entry commands |
| |
| 14.3.20 initrd |
| -------------- |
| |
| -- Command: initrd file |
| 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 (*note linux::) has |
| been run. See also *note GNU/Linux::. |
| |
| |
| File: grub.info, Node: initrd16, Next: insmod, Prev: initrd, Up: Command-line and menu entry commands |
| |
| 14.3.21 initrd16 |
| ---------------- |
| |
| -- Command: initrd16 file |
| 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 |
| (*note linux16::) has been run. See also *note GNU/Linux::. |
| |
| This command is only available on x86 systems. |
| |
| |
| File: grub.info, Node: insmod, Next: keystatus, Prev: initrd16, Up: Command-line and menu entry commands |
| |
| 14.3.22 insmod |
| -------------- |
| |
| -- Command: insmod module |
| Insert the dynamic GRUB module called MODULE. |
| |
| |
| File: grub.info, Node: keystatus, Next: linux, Prev: insmod, Up: Command-line and menu entry commands |
| |
| 14.3.23 keystatus |
| ----------------- |
| |
| -- Command: keystatus [`--shift'] [`--ctrl'] [`--alt'] |
| Return true if the Shift, Control, or Alt modifier 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 modifier status is only supported on some platforms. |
| If invoked without any options, the `keystatus' command returns |
| true if and only if checking key modifier status is supported. |
| |
| |
| File: grub.info, Node: linux, Next: linux16, Prev: keystatus, Up: Command-line and menu entry commands |
| |
| 14.3.24 linux |
| ------------- |
| |
| -- Command: linux file ... |
| Load a Linux kernel image from FILE. The rest of the line is |
| passed verbatim as the "kernel command-line". Any initrd must be |
| reloaded after using this command (*note initrd::). |
| |
| 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 (*note linux16::) avoids this restriction. |
| |
| |
| File: grub.info, Node: linux16, Next: list_env, Prev: linux, Up: Command-line and menu entry commands |
| |
| 14.3.25 linux16 |
| --------------- |
| |
| -- Command: linux16 file ... |
| Load a Linux kernel image from FILE 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 (*note |
| initrd16::). |
| |
| The kernel will be booted using the traditional 16-bit boot |
| protocol. As well as bypassing problems with `vga=' described in |
| *note linux::, 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. |
| |
| |
| File: grub.info, Node: list_env, Next: load_env, Prev: linux16, Up: Command-line and menu entry commands |
| |
| 14.3.26 list_env |
| ---------------- |
| |
| -- Command: list_env [`-f' file] |
| List all variables in the environment block file. *Note |
| Environment block::. |
| |
| The `-f' option overrides the default location of the environment |
| block. |
| |
| |
| File: grub.info, Node: load_env, Next: loopback, Prev: list_env, Up: Command-line and menu entry commands |
| |
| 14.3.27 load_env |
| ---------------- |
| |
| -- Command: load_env [`-f' file] |
| Load all variables from the environment block file into the |
| environment. *Note Environment block::. |
| |
| The `-f' option overrides the default location of the environment |
| block. |
| |
| |
| File: grub.info, Node: loopback, Next: ls, Prev: load_env, Up: Command-line and menu entry commands |
| |
| 14.3.28 loopback |
| ---------------- |
| |
| -- Command: loopback [`-d'] device file |
| Make the device named DEVICE correspond to the contents of the |
| filesystem image in FILE. For example: |
| |
| loopback loop0 /path/to/image |
| ls (loop0)/ |
| |
| With the `-d' option, delete a device previously created using this |
| command. |
| |
| |
| File: grub.info, Node: ls, Next: normal, Prev: loopback, Up: Command-line and menu entry commands |
| |
| 14.3.29 ls |
| ---------- |
| |
| -- Command: ls [arg ...] |
| List devices or files. |
| |
| With no arguments, print all devices known to GRUB. |
| |
| If the argument is a device name enclosed in parentheses (*note |
| Device syntax::), then list all files at the root directory of |
| that device. |
| |
| If the argument is a directory given as an absolute file name |
| (*note File name syntax::), then list the contents of that |
| directory. |
| |
| |
| File: grub.info, Node: normal, Next: normal_exit, Prev: ls, Up: Command-line and menu entry commands |
| |
| 14.3.30 normal |
| -------------- |
| |
| -- Command: normal [file] |
| Enter normal mode and display the GRUB menu. |
| |
| In normal mode, commands, filesystem modules, and cryptography |
| modules are automatically loaded, and the full GRUB script parser |
| is available. Other modules may be explicitly loaded using |
| `insmod' (*note insmod::). |
| |
| If a FILE is given, then commands will be read from that file. |
| 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' (*note |
| configfile::) for this. |
| |
| |
| File: grub.info, Node: normal_exit, Next: parttool, Prev: normal, Up: Command-line and menu entry commands |
| |
| 14.3.31 normal_exit |
| ------------------- |
| |
| -- Command: normal_exit |
| Exit normal mode (*note normal::). If this instance of normal |
| mode was not nested within another one, then return to rescue mode. |
| |
| |
| File: grub.info, Node: parttool, Next: password, Prev: normal_exit, Up: Command-line and menu entry commands |
| |
| 14.3.32 parttool |
| ---------------- |
| |
| -- Command: parttool partition commands |
| Make various modifications 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 flag 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 (prefix with `0x' to enter it in |
| hexadecimal). |
| |
| `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 *note |
| DOS/Windows::. |
| |
| |
| File: grub.info, Node: password, Next: password_pbkdf2, Prev: parttool, Up: Command-line and menu entry commands |
| |
| 14.3.33 password |
| ---------------- |
| |
| -- Command: password user clear-password |
| Define a user named USER with password CLEAR-PASSWORD. *Note |
| Security::. |
| |
| |
| File: grub.info, Node: password_pbkdf2, Next: play, Prev: password, Up: Command-line and menu entry commands |
| |
| 14.3.34 password_pbkdf2 |
| ----------------------- |
| |
| -- Command: password_pbkdf2 user hashed-password |
| Define a user named USER with password hash HASHED-PASSWORD. Use |
| `grub-mkpasswd-pbkdf2' (*note Invoking grub-mkpasswd-pbkdf2::) to |
| generate password hashes. *Note Security::. |
| |
| |
| File: grub.info, Node: play, Next: pxe_unload, Prev: password_pbkdf2, Up: Command-line and menu entry commands |
| |
| 14.3.35 play |
| ------------ |
| |
| -- Command: play file | tempo [pitch1 duration1] [pitch2 duration2] ... |
| Plays a tune |
| |
| If the argument is a file name (*note File name syntax::), play |
| the tune recorded in it. The file format is first 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. |
| |
| |
| File: grub.info, Node: pxe_unload, Next: read, Prev: play, Up: Command-line and menu entry commands |
| |
| 14.3.36 pxe_unload |
| ------------------ |
| |
| -- Command: pxe_unload |
| Unload the PXE environment (*note Network::). |
| |
| This command is only available on PC BIOS systems. |
| |
| |
| File: grub.info, Node: read, Next: reboot, Prev: pxe_unload, Up: Command-line and menu entry commands |
| |
| 14.3.37 read |
| ------------ |
| |
| -- Command: read [var] |
| 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. |
| |
| |
| File: grub.info, Node: reboot, Next: save_env, Prev: read, Up: Command-line and menu entry commands |
| |
| 14.3.38 reboot |
| -------------- |
| |
| -- Command: reboot |
| Reboot the computer. |
| |
| |
| File: grub.info, Node: save_env, Next: search, Prev: reboot, Up: Command-line and menu entry commands |
| |
| 14.3.39 save_env |
| ---------------- |
| |
| -- Command: save_env [`-f' file] var ... |
| Save the named variables from the environment to the environment |
| block file. *Note Environment block::. |
| |
| The `-f' option overrides the default location of the environment |
| block. |
| |
| |
| File: grub.info, Node: search, Next: sendkey, Prev: save_env, Up: Command-line and menu entry commands |
| |
| 14.3.40 search |
| -------------- |
| |
| -- Command: search [`--file'|`--label'|`--fs-uuid'] [`--set' [var]] |
| [`--no-floppy'] name |
| Search devices by file (`-f', `--file'), filesystem label (`-l', |
| `--label'), or filesystem UUID (`-u', `--fs-uuid'). |
| |
| If the `--set' option is used, the first device found is set as the |
| value of environment variable VAR. The default variable is `root'. |
| |
| The `--no-floppy' option prevents searching floppy 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. |
| |
| |
| File: grub.info, Node: sendkey, Next: set, Prev: search, Up: Command-line and menu entry commands |
| |
| 14.3.41 sendkey |
| --------------- |
| |
| -- Command: sendkey [`--num'|`--caps'|`--scroll'|`--insert'| |
| `--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 buffer 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 buffer). Keystroke names may be upper-case or lower-case |
| letters, digits, or taken from the following table: |
| |
| Name Key |
| --------------------------------------------------------------- |
| escape Escape |
| exclam ! |
| at @ |
| numbersign # |
| dollar $ |
| percent % |
| caret ^ |
| ampersand & |
| asterisk * |
| parenleft ( |
| parenright ) |
| minus - |
| underscore _ |
| equal = |
| plus + |
| backspace Backspace |
| tab Tab |
| bracketleft [ |
| braceleft { |
| bracketright ] |
| braceright } |
| enter Enter |
| control press and release Control |
| semicolon ; |
| colon : |
| quote ' |
| doublequote " |
| backquote ` |
| tilde ~ |
| shift press and release left Shift |
| backslash \ |
| bar | |
| comma , |
| less < |
| period . |
| greater > |
| slash / |
| question ? |
| rshift press and release right Shift |
| alt press and release Alt |
| space space bar |
| capslock Caps Lock |
| F1 F1 |
| F2 F2 |
| F3 F3 |
| F4 F4 |
| F5 F5 |
| F6 F6 |
| F7 F7 |
| F8 F8 |
| F9 F9 |
| F10 F10 |
| F11 F11 |
| F12 F12 |
| num1 1 (numeric keypad) |
| num2 2 (numeric keypad) |
| num3 3 (numeric keypad) |
| num4 4 (numeric keypad) |
| num5 5 (numeric keypad) |
| num6 6 (numeric keypad) |
| num7 7 (numeric keypad) |
| num8 8 (numeric keypad) |
| num9 9 (numeric keypad) |
| num0 0 (numeric keypad) |
| numperiod . (numeric keypad) |
| numend End (numeric keypad) |
| numdown Down (numeric keypad) |
| numpgdown Page Down (numeric keypad) |
| numleft Left (numeric keypad) |
| numcenter 5 with Num Lock inactive (numeric |
| keypad) |
| numright Right (numeric keypad) |
| numhome Home (numeric keypad) |
| numup Up (numeric keypad) |
| numpgup Page Up (numeric keypad) |
| numinsert Insert (numeric keypad) |
| numdelete Delete (numeric keypad) |
| numasterisk * (numeric keypad) |
| numminus - (numeric keypad) |
| numplus + (numeric keypad) |
| numslash / (numeric keypad) |
| numenter Enter (numeric keypad) |
| delete Delete |
| insert Insert |
| home Home |
| end End |
| pgdown Page Down |
| pgup Page Up |
| down Down |
| up Up |
| left Left |
| right Right |
| |
| As well as keystrokes, the `sendkey' command takes various options |
| that affect the BIOS keyboard status flags. These options take an |
| `on' or `off' parameter, specifying that the corresponding status |
| flag be set or unset; omitting the option for a given status flag |
| will leave that flag 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 flag options are |
| self-explanatory. |
| |
| If the `--no-led' option is given, the status flag options will |
| have no effect on keyboard LEDs. |
| |
| If the `sendkey' command is given multiple times, then only the |
| last invocation has any effect. |
| |
| Since `sendkey' manipulates the BIOS keyboard buffer, 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 effect. |
| |
| This command is only available on PC BIOS systems. |
| |
| |
| File: grub.info, Node: set, Next: true, Prev: sendkey, Up: Command-line and menu entry commands |
| |
| 14.3.42 set |
| ----------- |
| |
| -- Command: set [envvar=value] |
| Set the environment variable ENVVAR to VALUE. If invoked with no |
| arguments, print all environment variables with their values. |
| |
| |
| File: grub.info, Node: true, Next: unset, Prev: set, Up: Command-line and menu entry commands |
| |
| 14.3.43 true |
| ------------ |
| |
| -- Command: true |
| Do nothing, successfully. This is mainly useful in control |
| constructs such as `if' and `while' (*note Shell-like scripting::). |
| |
| |
| File: grub.info, Node: unset, Next: uppermem, Prev: true, Up: Command-line and menu entry commands |
| |
| 14.3.44 unset |
| ------------- |
| |
| -- Command: unset envvar |
| Unset the environment variable ENVVAR. |
| |
| |
| File: grub.info, Node: uppermem, Prev: unset, Up: Command-line and menu entry commands |
| |
| 14.3.45 uppermem |
| ---------------- |
| |
| This command is not yet implemented for GRUB 2, although it is planned. |
| |
| |
| File: grub.info, Node: Internationalisation, Next: Security, Prev: Commands, Up: Top |
| |
| 15 Charset |
| ********** |
| |
| GRUB uses UTF-8 internally other than in rendering where some |
| GRUB-specific appropriate representation is used. All text files |
| (including config) are assumed to be encoded in UTF-8. |
| |
| 16 Filesystems |
| ************** |
| |
| NTFS, JFS, UDF, HFS+, exFAT, long filenames in FAT, Joliet part of |
| ISO9660 are treated as UTF-16 as per specification. AFS and BFS are read |
| as UTF-8, again according to specification. 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 configured with |
| legacy charset but as long as the charset used is superset of ASCII you |
| should be able to access ASCII-named files. And it's recommended to |
| configure your system to use UTF-8 to access the filesystem, convmv may |
| help with migration. ISO9660 (plain) filenames are specified as being |
| ASCII or being described with unspecified escape sequences. GRUB |
| assumes that the ISO9660 names are UTF-8 (since any ASCII is valid |
| UTF-8). There are some old CD-ROMs which use CP437 in non-compliant |
| way. You're still able to access files with names containing only ASCII |
| characters on such filesystems though. You're also able to access any |
| file if the filesystem 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 filesystem |
| case-insensitivity however no attempt is performed at case conversion |
| of international characters so e.g. a file named lowercase greek alpha |
| is treated as different from the one named as uppercase alpha. The |
| filesystems in questions are NTFS (except POSIX namespace), HFS+ |
| (configurable at mkfs time, default insensitive), SFS (configurable at |
| mkfs time, default insensitive), JFS (configurable at mkfs time, |
| default sensitive), HFS, AFFS, FAT, exFAT and ZFS (configurable on |
| per-subvolume basis by property "casesensitivity", default sensitive). |
| On ZFS subvolumes marked as case insensitive files containing lowercase |
| international characters are inaccessible. Also like all supported |
| filesystems except HFS+ and ZFS (configurable on per-subvolume basis by |
| property "normalization", default none) GRUB makes no attempt at check |
| of canonical equivalence so a file name u-diaresis is treated as |
| distinct from u+combining diaresis. This however means that in order to |
| access file on HFS+ its name must be specified in normalisation form D. |
| On normalized ZFS subvolumes filenames out of normalisation are |
| inaccessible. |
| |
| 17 Output terminal |
| ****************** |
| |
| Firmware output console "console" on ARC and IEEE1275 are limited to |
| ASCII. BIOS firmware 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 firmware 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 specification |
| but results in correct rendering of right-to-left on some readers which |
| don't 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 aren't supported though. This should cover European, |
| Middle Eastern (if you don't mind lack of lam-alif ligature in Arabic) |
| and East Asian scripts. Notable unsupported scripts are Brahmic family |
| and derived as well as Mongolian, Tifinagh, Korean Jamo (precomposed |
| characters have no problem) and tonal writing (2e5-2e9). GRUB also |
| ignores deprecated (as specified in Unicode) characters (e.g. tags). |
| GRUB also doesn't 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. |
| |
| 18 Input terminal |
| ***************** |
| |
| Firmware console on BIOS, IEEE1275 and ARC doesn't allow you to enter |
| non-ASCII characters. EFI specification 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-char-per-keystroke. So no dead keys or advanced input method. Also |
| there is no keymap change hotkey. In practice it makes difficult to |
| enter any text using non-Latin alphabet. Moreover all current input |
| consumers are limited to ASCII. |
| |
| 19 Gettext |
| ********** |
| |
| GRUB supports being translated. For this you need to have language *.mo |
| files in $prefix/locale, load gettext module and set "lang" variable. |
| |
| 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. |
| |
| 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 don't contain any non-ASCII it should never be a |
| problem in practice. Case-sensitive identifiers are matched as raw |
| strings, no canonical equivalence check is performed. Case-insenstive |
| identifiers are matched as RAW but additionally [a-z] is equivalent to |
| [A-Z]. GRUB-defined identifiers use only ASCII and so should |
| user-defined ones. Identifiers containing non-ASCII may work but |
| aren't 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 aren't a valid field 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. |
| |
| |
| File: grub.info, Node: Security, Next: Platform limitations, Prev: Internationalisation, Up: Top |
| |
| 22 Authentication and authorisation |
| *********************************** |
| |
| By default, the boot loader interface is accessible to anyone with |
| physical access to the console: anyone can select and edit any menu |
| entry, and anyone can get direct access to a GRUB shell prompt. For |
| most systems, this is reasonable since anyone with direct physical |
| access has a variety of other ways to gain full access, and requiring |
| authentication at the boot loader level would only serve to make it |
| difficult to recover broken systems. |
| |
| However, in some environments, such as kiosks, it may be appropriate |
| to lock down the boot loader to require authentication before |
| performing certain operations. |
| |
| The `password' (*note password::) and `password_pbkdf2' (*note |
| password_pbkdf2::) commands can be used to define users, each of which |
| has an associated password. `password' sets the password in plain |
| text, requiring `grub.cfg' to be secure; `password_pbkdf2' sets the |
| password hashed using the Password-Based Key Derivation Function (RFC |
| 2898), requiring the use of `grub-mkpasswd-pbkdf2' (*note Invoking |
| grub-mkpasswd-pbkdf2::) to generate password hashes. |
| |
| In order to enable authentication support, the `superusers' |
| environment variable must be set to a list of usernames, separated by |
| any of spaces, commas, semicolons, pipes, or ampersands. Superusers |
| are permitted to use the GRUB command line, edit menu entries, and |
| execute any menu entry. If `superusers' is set, then use of the |
| command line is automatically restricted to superusers. |
| |
| Other users may be given access to specific menu entries by giving a |
| list of usernames (as above) using the `--users' option to the |
| `menuentry' command (*note menuentry::). If the `--unrestricted' |
| option is used for a menu entry, then that entry is unrestricted. If |
| the `--users' option is not used for a menu entry, then that only |
| superusers are able to use it. |
| |
| Putting this together, a typical `grub.cfg' fragment might look like |
| this: |
| |
| set superusers="root" |
| password_pbkdf2 root grub.pbkdf2.sha512.10000.biglongstring |
| password user1 insecure |
| |
| menuentry "May be run by any user" --unrestricted { |
| set root=(hd0,1) |
| linux /vmlinuz |
| } |
| |
| menuentry "Superusers only" --users "" { |
| set root=(hd0,1) |
| linux /vmlinuz single |
| } |
| |
| menuentry "May be run by user1 or a superuser" --users user1 { |
| set root=(hd0,2) |
| chainloader +1 |
| } |
| |
| The `grub-mkconfig' program does not yet have built-in support for |
| generating configuration files with authentication. You can use |
| `/etc/grub.d/40_custom' to add simple superuser authentication, by |
| adding `set superusers=' and `password' or `password_pbkdf2' commands. |
| |
| |
| File: grub.info, Node: Platform limitations, Next: Platform-specific operations, Prev: Security, Up: Top |
| |
| 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 (firmware doesn't 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 firmware-assisted console. gfxterm is |
| always Unicode (see Internationalisation section for its limitations). |
| Serial is configurable 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 doesn't 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 firmware |
| |
| 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 firmware console to serial if it |
| allows so. |
| |
| Direct ATA/AHCI support allows to circumvent various firmware |
| limitations but isn't needed for normal operation except on baremetal |
| ports. |
| |
| AT keyboard support allows keyboard layout remapping and support for |
| keys not available through firmware. It isn't needed for normal |
| operation except baremetal ports. |
| |
| USB support provides benefits 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 it's 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 first hole. |
| |
| BIOS Coreboot Multiboot Qemu |
| video yes yes yes yes |
| console CP437 CP437 CP437 CP437 |
| charset |
| 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 |
| cpuid partial partial partial partial |
| hints guess guess guess guess |
| PCI yes yes yes yes |
| badram yes yes yes yes |
| compression always pointless no no |
| exit yes no no no |
| |
| ia32 EFI amd64 EFI ia32 IEEE1275 Itanium |
| video yes yes no no |
| console Unicode Unicode ASCII Unicode |
| charset |
| network yes yes yes yes |
| ATA/AHCI yes yes yes no |
| AT keyboard yes yes yes no |
| USB yes yes yes no |
| chainloader local local no local |
| cpuid partial partial partial no |
| hints guess guess good guess |
| PCI yes yes yes no |
| badram yes yes no yes |
| compression no no no no |
| exit yes yes yes yes |
| |
| Loongson sparc64 Powerpc ARC |
| video yes no yes no |
| console N/A ASCII ASCII ASCII |
| charset |
| network no yes (*) yes no |
| ATA/AHCI yes no no no |
| AT keyboard yes no no no |
| USB yes no no no |
| chainloader yes no no no |
| cpuid no no no no |
| hints good good good no |
| PCI yes no no no |
| badram yes (*) no no no |
| compression configurable no no configurable |
| exit no yes yes yes |
| |
| MIPS qemu emu |
| video no yes |
| console CP437 ASCII |
| charset |
| network no yes |
| ATA/AHCI yes no |
| AT keyboard yes no |
| USB N/A yes |
| chainloader yes no |
| cpuid no no |
| hints guess no |
| PCI no no |
| badram yes (*) no |
| compression configurable no |
| exit no yes |
| |
| |
| File: grub.info, Node: Platform-specific operations, Next: Supported kernels, Prev: Platform limitations, Up: Top |
| |
| 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 |
| |
| * efi: lsefisystab, lssal, lsefimmap |
| |
| * i386-pc: lsapm |
| |
| * acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi): |
| lsacpi |
| |
| Workarounds for platform-specific issues: |
| * i386-efi/x86_64-efi: loadbios, fixvideo |
| |
| * acpi-enabled (i386-pc, i386-coreboot, i386-multiboot, *-efi): |
| 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 |
| |
| |
| File: grub.info, Node: Supported kernels, Next: Troubleshooting, Prev: Platform-specific operations, Up: Top |
| |
| 25 Supported boot targets |
| ************************* |
| |
| X86 support is summarised in the following table. "Yes" means that the |
| kernel works on the given platform, "crashes" means an early kernel |
| crash which we hope will be fixed by concerned kernel developers. "no" |
| means GRUB doesn't load the given kernel on a given platform. |
| "headless" means that the kernel works but lacks console drivers (you |
| can still use serial or network console). In case of "no" and |
| "crashes" the reason is given in footnote. |
| BIOS Coreboot |
| BIOS chainloading yes no (1) |
| NTLDR yes no (1) |
| Plan9 yes no (1) |
| Freedos yes no (1) |
| FreeBSD bootloader yes crashes (1) |
| 32-bit kFreeBSD yes crashes (2,6) |
| 64-bit kFreeBSD yes crashes (2,6) |
| 32-bit kNetBSD yes crashes (1) |
| 64-bit kNetBSD yes crashes (2) |
| 32-bit kOpenBSD yes yes |
| 64-bit kOpenBSD yes yes |
| Multiboot yes yes |
| Multiboot2 yes yes |
| 32-bit Linux (legacy protocol) yes no (1) |
| 64-bit Linux (legacy protocol) yes no (1) |
| 32-bit Linux (modern protocol) yes yes |
| 64-bit Linux (modern protocol) yes yes |
| 32-bit XNU yes ? |
| 64-bit XNU yes ? |
| 32-bit EFI chainloader no (3) no (3) |
| 64-bit EFI chainloader no (3) no (3) |
| Appleloader no (3) no (3) |
| |
| Multiboot Qemu |
| BIOS chainloading no (1) no (1) |
| NTLDR no (1) no (1) |
| Plan9 no (1) no (1) |
| FreeDOS no (1) no (1) |
| FreeBSD bootloader crashes (1) crashes (1) |
| 32-bit kFreeBSD crashes (6) crashes (6) |
| 64-bit kFreeBSD crashes (6) crashes (6) |
| 32-bit kNetBSD crashes (1) crashes (1) |
| 64-bit kNetBSD yes yes |
| 32-bit kOpenBSD yes yes |
| 64-bit kOpenBSD yes yes |
| Multiboot yes yes |
| Multiboot2 yes yes |
| 32-bit Linux (legacy protocol) no (1) no (1) |
| 64-bit Linux (legacy protocol) no (1) no (1) |
| 32-bit Linux (modern protocol) yes yes |
| 64-bit Linux (modern protocol) yes yes |
| 32-bit XNU ? ? |
| 64-bit XNU ? ? |
| 32-bit EFI chainloader no (3) no (3) |
| 64-bit EFI chainloader no (3) no (3) |
| Appleloader no (3) no (3) |
| |
| ia32 EFI amd64 EFI |
| BIOS chainloading no (1) no (1) |
| NTLDR no (1) no (1) |
| Plan9 no (1) no (1) |
| FreeDOS no (1) no (1) |
| FreeBSD bootloader crashes (1) crashes (1) |
| 32-bit kFreeBSD headless headless |
| 64-bit kFreeBSD headless headless |
| 32-bit kNetBSD crashes (1) crashes (1) |
| 64-bit kNetBSD yes yes |
| 32-bit kOpenBSD headless headless |
| 64-bit kOpenBSD headless headless |
| Multiboot yes yes |
| Multiboot2 yes yes |
| 32-bit Linux (legacy protocol) no (1) no (1) |
| 64-bit Linux (legacy protocol) no (1) no (1) |
| 32-bit Linux (modern protocol) yes yes |
| 64-bit Linux (modern protocol) yes yes |
| 32-bit XNU yes yes |
| 64-bit XNU yes (5) yes |
| 32-bit EFI chainloader yes no (4) |
| 64-bit EFI chainloader no (4) yes |
| Appleloader yes yes |
| |
| ia32 IEEE1275 |
| BIOS chainloading no (1) |
| NTLDR no (1) |
| Plan9 no (1) |
| FreeDOS no (1) |
| FreeBSD bootloader crashes (1) |
| 32-bit kFreeBSD crashes (6) |
| 64-bit kFreeBSD crashes (6) |
| 32-bit kNetBSD crashes (1) |
| 64-bit kNetBSD ? |
| 32-bit kOpenBSD ? |
| 64-bit kOpenBSD ? |
| Multiboot ? |
| Multiboot2 ? |
| 32-bit Linux (legacy protocol) no (1) |
| 64-bit Linux (legacy protocol) no (1) |
| 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 isn't available |
| |
| 3. EFI only |
| |
| 4. 32-bit and 64-bit EFI have different structures and work in |
| different CPU modes so it's not possible to chainload 32-bit |
| bootloader on 64-bit platform and vice-versa |
| |
| 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. |
| |
| 26 Boot tests |
| ************* |
| |
| As you have seen in previous chapter the support matrix is pretty big |
| and some of the configurations are only rarely used. To ensure the |
| quality bootchecks are available for all x86 targets except EFI |
| chainloader, Appleloader and XNU. All x86 platforms have bootcheck |
| facility except ieee1275. Multiboot, multiboot2, BIOS chainloader, |
| ntldr and freebsd-bootloader boot targets are tested only with a fake |
| kernel images. Only Linux is tested among the payloads using Linux |
| protocols. |
| |
| Following variables must be defined: |
| |
| GRUB_PAYLOADS_DIR directory containing the required kernels |
| GRUB_CBFSTOOL cbfstoll from Coreboot package (for coreboot |
| platform only) |
| GRUB_COREBOOT_ROM empty Coreboot ROM |
| GRUB_QEMU_OPTS additional options to be supplied to QEMU |
| |
| Required files 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. |
| knetbsd.x86_64, same from 64-bit kNetBSD |
| 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 |
| |
| |
| File: grub.info, Node: Troubleshooting, Next: Invoking grub-install, Prev: Supported kernels, Up: Top |
| |
| 27 Error messages produced by GRUB |
| ********************************** |
| |
| * Menu: |
| |
| * GRUB only offers a rescue shell:: |
| |
| |
| File: grub.info, Node: GRUB only offers a rescue shell, Up: Troubleshooting |
| |
| 27.1 GRUB only offers a rescue shell |
| ==================================== |
| |
| GRUB's normal start-up procedure involves setting the `prefix' |
| environment variable to a value set in the core image by |
| `grub-install', setting the `root' variable to match, loading the |
| `normal' module from the prefix, and running the `normal' command |
| (*note normal::). This command is responsible for reading |
| `/boot/grub/grub.cfg', running the menu, and doing all the useful |
| things GRUB is supposed to do. |
| |
| If, instead, you only get a rescue shell, this usually means that |
| GRUB failed to load the `normal' module for some reason. It may be |
| possible to work around this temporarily: for instance, if the reason |
| for the failure is that `prefix' is wrong (perhaps it refers to the |
| wrong device, or perhaps the path to `/boot/grub' was not correctly |
| made relative to the device), then you can correct this and enter |
| normal mode manually: |
| |
| # Inspect the current prefix (and other preset variables): |
| set |
| # Find out which devices are available: |
| ls |
| # Set to the correct value, which might be something like this: |
| set prefix=(hd0,1)/grub |
| set root=(hd0,1) |
| insmod normal |
| normal |
| |
| However, any problem that leaves you in the rescue shell probably |
| means that GRUB was not correctly installed. It may be more useful to |
| try to reinstall it properly using `grub-install DEVICE' (*note |
| Invoking grub-install::). When doing this, there are a few things to |
| remember: |
| |
| * Drive ordering in your operating system may not be the same as the |
| boot drive ordering used by your firmware. Do not assume that |
| your first hard drive (e.g. `/dev/sda') is the one that your |
| firmware will boot from. `device.map' (*note Device map::) can be |
| used to override this, but it is usually better to use UUIDs or |
| file system labels and avoid depending on drive ordering entirely. |
| |
| * At least on BIOS systems, if you tell `grub-install' to install |
| GRUB to a partition but GRUB has already been installed in the |
| master boot record, then the GRUB installation in the partition |
| will be ignored. |
| |
| * If possible, it is generally best to avoid installing GRUB to a |
| partition (unless it is a special partition for the use of GRUB |
| alone, such as the BIOS Boot Partition used on GPT). Doing this |
| means that GRUB may stop being able to read its core image due to |
| a file system moving blocks around, such as while defragmenting, |
| running checks, or even during normal operation. Installing to |
| the whole disk device is normally more robust. |
| |
| * Check that GRUB actually knows how to read from the device and |
| file system containing `/boot/grub'. It will not be able to read |
| from encrypted devices, nor from file systems for which support |
| has not yet been added to GRUB. |
| |
| |
| File: grub.info, Node: Invoking grub-install, Next: Invoking grub-mkconfig, Prev: Troubleshooting, Up: Top |
| |
| 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 specified 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. |
| |
| |
| File: grub.info, Node: Invoking grub-mkconfig, Next: Invoking grub-mkpasswd-pbkdf2, Prev: Invoking grub-install, Up: Top |
| |
| 29 Invoking grub-mkconfig |
| ************************* |
| |
| The program `grub-mkconfig' generates a configuration file for GRUB |
| (*note Simple configuration::). |
| |
| 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 configuration file to FILE. The default is to |
| send it to standard output. |
| |
| |
| File: grub.info, Node: Invoking grub-mkpasswd-pbkdf2, Next: Invoking grub-mkrescue, Prev: Invoking grub-mkconfig, Up: Top |
| |
| 30 Invoking grub-mkpasswd-pbkdf2 |
| ******************************** |
| |
| The program `grub-mkpasswd-pbkdf2' generates password hashes for GRUB |
| (*note Security::). |
| |
| 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. |
| |
| |
| File: grub.info, Node: Invoking grub-mkrescue, Next: Invoking grub-probe, Prev: Invoking grub-mkpasswd-pbkdf2, Up: Top |
| |
| 31 Invoking grub-mkrescue |
| ************************* |
| |
| The program `grub-mkrescue' generates a bootable GRUB rescue image |
| (*note Making a GRUB bootable CD-ROM::). |
| |
| 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 files to the image: |
| |
| mkdir -p disk/boot/grub |
| (add extra files 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 FILE. 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' files respectively to the |
| DIR directory as well as including them in the image. |
| |
| `--xorriso=FILE' |
| Use FILE as the `xorriso' program, rather than the built-in |
| default. |
| |
| `--grub-mkimage=FILE' |
| Use FILE as the `grub-mkimage' program, rather than the built-in |
| default. |
| |
| |
| File: grub.info, Node: Invoking grub-probe, Next: Obtaining and Building GRUB, Prev: Invoking grub-mkrescue, Up: Top |
| |
| 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 filesystem path (such as `/boot/grub'), |
| and `grub-probe' will print information about the device |
| containing that part of the filesystem. |
| |
| `-m FILE' |
| `--device-map=FILE' |
| Use FILE as the device map (*note Device map::) rather than the |
| default, usually `/boot/grub/device.map'. |
| |
| `-t TARGET' |
| `--target=TARGET' |
| Print information about the given path or device as defined by |
| TARGET. The available targets and their meanings are: |
| |
| `fs' |
| GRUB filesystem module. |
| |
| `fs_uuid' |
| Filesystem Universally Unique Identifier (UUID). |
| |
| `fs_label' |
| Filesystem label. |
| |
| `drive' |
| GRUB device name. |
| |
| `device' |
| System device name. |
| |
| `partmap' |
| GRUB partition map module. |
| |
| `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 (*note search::). |
| |
| `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 firmware. |
| |
| `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. |
| |
| `-v' |
| `--verbose' |
| Print verbose messages. |
| |
| |
| File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking grub-probe, Up: Top |
| |
| Appendix A How to obtain and build GRUB |
| *************************************** |
| |
| *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 file will be |
| named grub-version.tar.gz. The current version is 2.00, so the file 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 file `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-download.en.html' for more |
| information. |
| |
| |
| File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top |
| |
| Appendix B Reporting bugs |
| ************************* |
| |
| These are the guideline for how to report bugs. Take a look at this |
| list below before you submit bugs: |
| |
| 1. Before getting unsettled, read this manual through and through. |
| Also, see the GNU GRUB FAQ |
| (http://www.gnu.org/software/grub/grub-faq.html). |
| |
| 2. Always mention the information on your GRUB. The version number |
| and the configuration are quite important. If you build it |
| yourself, write the options specified to the configure script and |
| your operating system, including the versions of gcc and binutils. |
| |
| 3. If you have trouble with the installation, inform us of how you |
| installed GRUB. Don't omit error messages, if any. Just `GRUB hangs |
| up when it boots' is not enough. |
| |
| The information on your hardware is also essential. These are |
| especially important: the geometries and the partition tables of |
| your hard disk drives and your BIOS. |
| |
| 4. If GRUB cannot boot your operating system, write down _everything_ |
| you see on the screen. Don't paraphrase them, like `The foo OS |
| crashes with GRUB, even though it can boot with the bar boot |
| loader just fine'. Mention the commands you executed, the messages |
| printed by them, and information on your operating system |
| including the version number. |
| |
| 5. Explain what you wanted to do. It is very useful to know your |
| purpose and your wish, and how GRUB didn't satisfy you. |
| |
| 6. If you can investigate the problem yourself, please do. That will |
| give you and us much more information on the problem. Attaching a |
| patch is even better. |
| |
| When you attach a patch, make the patch in unified diff format, and |
| write ChangeLog entries. But, even when you make a patch, don't |
| forget to explain the problem, so that we can understand what your |
| patch is for. |
| |
| 7. Write down anything that you think might be related. Please |
| understand that we often need to reproduce the same problem you |
| encountered in our environment. So your information should be |
| sufficient for us to do the same thing--Don't forget that we |
| cannot see your computer directly. If you are not sure whether to |
| state a fact or leave it out, state it! Reporting too many things |
| is much better than omitting something important. |
| |
| If you follow the guideline above, submit a report to the Bug |
| Tracking System (http://savannah.gnu.org/bugs/?group=grub). |
| Alternatively, you can submit a report via electronic mail to |
| <bug-grub@gnu.org>, but we strongly recommend that you use the Bug |
| Tracking System, because e-mail can be passed over easily. |
| |
| Once we get your report, we will try to fix the bugs. |
| |
| |
| File: grub.info, Node: Future, Next: Copying This Manual, Prev: Reporting bugs, Up: Top |
| |
| Appendix C Where GRUB will go |
| ***************************** |
| |
| GRUB 2 is now quite stable and used in many production systems. We are |
| currently working towards a 2.0 release. |
| |
| If you are interested in the development of GRUB 2, take a look at |
| the homepage (http://www.gnu.org/software/grub/grub.html). |
| |
| |
| File: grub.info, Node: Copying This Manual, Next: Index, Prev: Future, Up: Top |
| |
| Appendix D Copying This Manual |
| ****************************** |
| |
| * Menu: |
| |
| * GNU Free Documentation License:: License for copying this manual. |
| |
| |
| File: grub.info, Node: GNU Free Documentation License, Up: Copying This Manual |
| |
| D.1 GNU Free Documentation License |
| ================================== |
| |
| Version 1.2, November 2002 |
| |
| Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. |
| 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| |
| 0. PREAMBLE |
| |
| The purpose of this License is to make a manual, textbook, or other |
| functional and useful document "free" in the sense of freedom: to |
| assure everyone the effective freedom to copy and redistribute it, |
| with or without modifying it, either commercially or |
| noncommercially. Secondarily, this License preserves for the |
| author and publisher a way to get credit for their work, while not |
| being considered responsible for modifications made by others. |
| |
| This License is a kind of "copyleft", which means that derivative |
| works of the document must themselves be free in the same sense. |
| It complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| |
| We have designed this License in order to use it for manuals for |
| free software, because free software needs free documentation: a |
| free program should come with manuals providing the same freedoms |
| that the software does. But this License is not limited to |
| software manuals; it can be used for any textual work, regardless |
| of subject matter or whether it is published as a printed book. |
| We recommend this License principally for works whose purpose is |
| instruction or reference. |
| |
| 1. APPLICABILITY AND DEFINITIONS |
| |
| This License applies to any manual or other work, in any medium, |
| that contains a notice placed by the copyright holder saying it |
| can be distributed under the terms of this License. Such a notice |
| grants a world-wide, royalty-free license, unlimited in duration, |
| to use that work under the conditions stated herein. The |
| "Document", below, refers to any such manual or work. Any member |
| of the public is a licensee, and is addressed as "you". You |
| accept the license if you copy, modify or distribute the work in a |
| way requiring permission under copyright law. |
| |
| A "Modified Version" of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A "Secondary Section" is a named appendix or a front-matter section |
| of the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document's overall |
| subject (or to related matters) and contains nothing that could |
| fall directly within that overall subject. (Thus, if the Document |
| is in part a textbook of mathematics, a Secondary Section may not |
| explain any mathematics.) The relationship could be a matter of |
| historical connection with the subject or with related matters, or |
| of legal, commercial, philosophical, ethical or political position |
| regarding them. |
| |
| 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 fit the above definition 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 specification 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 file format whose markup, or absence of |
| markup, has been arranged to thwart or discourage subsequent |
| modification 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 modification. 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 |
| work's 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 specific 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 definition. |
| |
| 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 effect on the meaning of this License. |
| |
| 2. VERBATIM COPYING |
| |
| 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 Document's 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 fit |
| legibly, you should put the first ones listed (as many as fit |
| 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 Modified Version of the Document |
| under the conditions of sections 2 and 3 above, provided that you |
| release the Modified Version under precisely this License, with |
| the Modified Version filling the role of the Document, thus |
| licensing distribution and modification of the Modified Version to |
| whoever possesses a copy of it. In addition, you must do these |
| things in the Modified 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, 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 modifications in |
| the Modified Version, together with at least five of the |
| principal authors of the Document (all of its principal |
| authors, if it has fewer than five), unless they release you |
| from this requirement. |
| |
| C. State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| D. Preserve all the copyright notices of the Document. |
| |
| E. Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| F. Include, immediately after the copyright notices, a license |
| notice giving the public permission to use the Modified |
| 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 Document's |
| 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 Modified 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 Modified 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 Modified Version. |
| |
| N. Do not retitle any existing section to be Entitled |
| "Endorsements" or to conflict in title with any Invariant |
| Section. |
| |
| O. Preserve any Warranty Disclaimers. |
| |
| If the Modified 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 titles to the list of Invariant Sections in the Modified |
| Version's 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 Modified Version by various |
| parties--for example, statements of peer review or that the text |
| has been approved by an organization as the authoritative |
| definition of a standard. |
| |
| You may add a passage of up to five 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 Modified 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 Modified Version. |
| |
| 5. COMBINING DOCUMENTS |
| |
| You may combine the Document with other documents released under |
| this License, under the terms defined in section 4 above for |
| modified versions, provided that you include in the combination |
| all of the Invariant Sections of all of the original documents, |
| unmodified, 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 different 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. |
| |
| 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 compilation's 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 Document's 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 modification, 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 |
| differ 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 specifies 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 specified 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. |
| |
| D.1.1 ADDENDUM: How to use this License for your documents |
| ---------------------------------------------------------- |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and license |
| notices just after the title page: |
| |
| Copyright (C) YEAR YOUR NAME. |
| 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, no Front-Cover Texts, and no Back-Cover |
| Texts. A copy of the license is included in the section entitled ``GNU |
| Free Documentation License''. |
| |
| 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. |
| |
| |
| File: grub.info, Node: Index, Prev: Copying This Manual, Up: Top |
| |
| Index |
| ***** |
| |
| [index] |
| * Menu: |
| |
| * acpi: acpi. (line 11) |
| * badram: badram. (line 7) |
| * blocklist: blocklist. (line 7) |
| * boot: boot. (line 7) |
| * cat: cat. (line 7) |
| * chainloader: chainloader. (line 7) |
| * cmp: cmp. (line 7) |
| * configfile: configfile. (line 7) |
| * cpuid: cpuid. (line 7) |
| * crc: crc. (line 7) |
| * date: date. (line 7) |
| * drivemap: drivemap. (line 7) |
| * echo: echo. (line 7) |
| * export: export. (line 7) |
| * false: false. (line 7) |
| * FDL, GNU Free Documentation License: GNU Free Documentation License. |
| (line 6) |
| * gettext: gettext. (line 7) |
| * gptsync: gptsync. (line 7) |
| * halt: halt. (line 7) |
| * help: help. (line 7) |
| * initrd: initrd. (line 7) |
| * initrd16: initrd16. (line 7) |
| * insmod: insmod. (line 7) |
| * keystatus: keystatus. (line 7) |
| * linux: linux. (line 7) |
| * linux16: linux16. (line 7) |
| * list_env: list_env. (line 7) |
| * load_env: load_env. (line 7) |
| * loopback: loopback. (line 7) |
| * ls: ls. (line 7) |
| * menuentry: menuentry. (line 8) |
| * normal: normal. (line 7) |
| * normal_exit: normal_exit. (line 7) |
| * parttool: parttool. (line 7) |
| * password: password. (line 7) |
| * password_pbkdf2: password_pbkdf2. (line 7) |
| * play: play. (line 7) |
| * pxe_unload: pxe_unload. (line 7) |
| * read: read. (line 7) |
| * reboot: reboot. (line 7) |
| * save_env: save_env. (line 7) |
| * search: search. (line 8) |
| * sendkey: sendkey. (line 12) |
| * serial: serial. (line 8) |
| * set: set. (line 7) |
| * submenu: submenu. (line 8) |
| * terminal_input: terminal_input. (line 8) |
| * terminal_output: terminal_output. (line 8) |
| * terminfo: terminfo. (line 7) |
| * true: true. (line 7) |
| * unset: unset. (line 7) |
| |
| |
| |
| Tag Table: |
| Node: Top1043 |
| Node: Introduction3645 |
| Node: Overview4089 |
| Node: Overview-Footnotes6073 |
| Ref: Overview-Footnote-16134 |
| Node: History6295 |
| Node: Changes from GRUB Legacy8383 |
| Node: Features10859 |
| Node: Features-Footnotes17218 |
| Ref: Features-Footnote-117279 |
| Ref: Features-Footnote-217425 |
| Node: Role of a boot loader17570 |
| Node: Role of a boot loader-Footnotes18908 |
| Ref: Role of a boot loader-Footnote-118995 |
| Node: Naming convention19074 |
| Node: Installation21949 |
| Node: Installing GRUB using grub-install23052 |
| Node: Making a GRUB bootable CD-ROM25223 |
| Node: Making a GRUB bootable CD-ROM-Footnotes27077 |
| Ref: Making a GRUB bootable CD-ROM-Footnote-127180 |
| Node: Device map27255 |
| Node: BIOS installation29236 |
| Node: Booting32613 |
| Node: General boot methods33069 |
| Node: Loading an operating system directly33809 |
| Node: Chain-loading34540 |
| Node: Loopback booting35511 |
| Node: OS-specific notes37174 |
| Node: GNU/Hurd37452 |
| Node: GNU/Linux38574 |
| Node: DOS/Windows40202 |
| Node: Configuration41975 |
| Node: Simple configuration42585 |
| Node: Shell-like scripting52699 |
| Node: Shell-like scripting-Footnotes60630 |
| Ref: Shell-like scripting-Footnote-160715 |
| Node: Multi-boot manual config60842 |
| Node: Embedded configuration64467 |
| Node: Theme file format67304 |
| Ref: Pixmap-styled progress bar68727 |
| Ref: Plain progress bar68739 |
| Ref: An example of the slices (in red) used for a terminal window. This drawing was created and sliced in Inkscape_72237 |
| Node: Network86459 |
| Node: Serial terminal88609 |
| Node: Vendor power-on keys90836 |
| Node: Images92666 |
| Node: Filesystem97626 |
| Node: Device syntax98313 |
| Node: File name syntax100696 |
| Node: Block list syntax101450 |
| Node: Interface102183 |
| Node: Command-line interface103005 |
| Node: Command-line interface-Footnotes104946 |
| Ref: Command-line interface-Footnote-1105035 |
| Node: Menu interface105130 |
| Node: Menu entry editor106140 |
| Node: Environment106878 |
| Node: Special environment variables107582 |
| Node: biosnum108333 |
| Node: chosen108847 |
| Node: color_highlight109289 |
| Node: color_normal109695 |
| Node: debug110317 |
| Node: default110664 |
| Node: fallback111591 |
| Node: gfxmode111922 |
| Node: gfxpayload112655 |
| Node: gfxterm_font113807 |
| Node: icondir114106 |
| Node: lang114422 |
| Node: locale_dir114891 |
| Node: menu_color_highlight115400 |
| Node: menu_color_normal115896 |
| Node: net_pxe_boot_file116389 |
| Node: net_pxe_dhcp_server_name116600 |
| Node: net_pxe_domain116822 |
| Node: net_pxe_extensionspath117029 |
| Node: net_pxe_hostname117244 |
| Node: net_pxe_ip117443 |
| Node: net_pxe_mac117619 |
| Node: net_pxe_rootpath117797 |
| Node: pager117980 |
| Node: prefix118234 |
| Node: pxe_blksize118683 |
| Node: pxe_default_gateway118860 |
| Node: pxe_default_server119065 |
| Node: root119261 |
| Node: superusers119802 |
| Node: theme120050 |
| Node: timeout120371 |
| Node: Environment block120868 |
| Node: Commands122300 |
| Node: Menu-specific commands123145 |
| Node: menuentry123872 |
| Node: submenu125006 |
| Node: General commands125533 |
| Node: serial126029 |
| Node: terminal_input127074 |
| Node: terminal_output127740 |
| Node: terminfo128407 |
| Node: Command-line and menu entry commands129542 |
| Node: acpi132513 |
| Node: badram133552 |
| Node: blocklist134594 |
| Node: boot134828 |
| Node: cat135149 |
| Node: chainloader135784 |
| Node: cmp136406 |
| Node: configfile136957 |
| Node: cpuid137257 |
| Node: crc137722 |
| Node: date137912 |
| Node: drivemap138451 |
| Node: echo139254 |
| Node: export140191 |
| Node: false140501 |
| Node: gettext140797 |
| Node: gptsync141244 |
| Node: halt142189 |
| Node: help142515 |
| Node: initrd142978 |
| Node: initrd16143390 |
| Node: insmod143895 |
| Node: keystatus144117 |
| Node: linux144755 |
| Node: linux16145658 |
| Node: list_env146372 |
| Node: load_env146726 |
| Node: loopback147104 |
| Node: ls147552 |
| Node: normal148097 |
| Node: normal_exit148856 |
| Node: parttool149178 |
| Node: password150683 |
| Node: password_pbkdf2150965 |
| Node: play151373 |
| Node: pxe_unload152125 |
| Node: read152404 |
| Node: reboot152753 |
| Node: save_env152938 |
| Node: search153324 |
| Node: sendkey154102 |
| Node: set160376 |
| Node: true160674 |
| Node: unset160959 |
| Node: uppermem161165 |
| Node: Internationalisation161366 |
| Node: Security167965 |
| Node: Platform limitations170787 |
| Node: Platform-specific operations177174 |
| Node: Supported kernels178160 |
| Node: Troubleshooting186151 |
| Node: GRUB only offers a rescue shell186377 |
| Node: Invoking grub-install189303 |
| Node: Invoking grub-mkconfig190681 |
| Node: Invoking grub-mkpasswd-pbkdf2191318 |
| Node: Invoking grub-mkrescue191976 |
| Node: Invoking grub-probe193731 |
| Node: Obtaining and Building GRUB196327 |
| Node: Reporting bugs197564 |
| Node: Future200367 |
| Node: Copying This Manual200767 |
| Node: GNU Free Documentation License200995 |
| Node: Index223403 |
| |
| End Tag Table |