| \input texinfo |
| @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename grub.info |
| @include version.texi |
| @settitle GNU GRUB Manual @value{VERSION} |
| @c Unify all our little indices for now. |
| @syncodeindex fn cp |
| @syncodeindex vr cp |
| @syncodeindex ky cp |
| @syncodeindex pg cp |
| @syncodeindex tp cp |
| @c %**end of header |
| |
| @footnotestyle separate |
| @paragraphindent 3 |
| @finalout |
| |
| @copying |
| This manual is for GNU GRUB (version @value{VERSION}, |
| @value{UPDATED}). |
| |
| Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012,2013 Free Software Foundation, Inc. |
| |
| @quotation |
| 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. |
| @end quotation |
| @end copying |
| |
| @dircategory Kernel |
| @direntry |
| * 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-mkrelpath: (grub)Invoking grub-mkrelpath. |
| * grub-mkrescue: (grub)Invoking grub-mkrescue. Make a GRUB rescue image |
| * grub-mount: (grub)Invoking grub-mount. Mount a file system using GRUB |
| * grub-probe: (grub)Invoking grub-probe. Probe device information |
| * grub-script-check: (grub)Invoking grub-script-check. |
| @end direntry |
| |
| @setchapternewpage odd |
| |
| @titlepage |
| @sp 10 |
| @title the GNU GRUB manual |
| @subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. |
| @author Gordon Matzigkeit |
| @author Yoshinori K. Okuji |
| @author Colin Watson |
| @author Colin D. Bennett |
| @c The following two commands start the copyright page. |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| @end titlepage |
| |
| @c Output the table of contents at the beginning. |
| @contents |
| |
| @finalout |
| @headings double |
| |
| @ifnottex |
| @node Top |
| @top 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 @value{VERSION}. |
| |
| @insertcopying |
| @end ifnottex |
| |
| @menu |
| * Introduction:: Capturing the spirit of GRUB |
| * Naming convention:: Names of your drives in GRUB |
| * OS-specific notes about grub tools:: |
| Some notes about OS-specific behaviour of GRUB |
| tools |
| * 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 |
| * Core image size limitation:: GRUB image files size limitations |
| * 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, authorisation, and signatures |
| * 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-mkrelpath:: Make system path relative to its root |
| * Invoking grub-mkrescue:: Make a GRUB rescue image |
| * Invoking grub-mount:: Mount a file system using GRUB |
| * Invoking grub-probe:: Probe device information for GRUB |
| * Invoking grub-script-check:: Check GRUB script file for syntax errors |
| * 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:: |
| @end menu |
| |
| |
| @node Introduction |
| @chapter 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 |
| @end menu |
| |
| |
| @node Overview |
| @section Overview |
| |
| Briefly, a @dfn{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 @dfn{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@footnote{@dfn{chain-load} is the mechanism for loading |
| unsupported operating systems by loading another boot loader. It is |
| typically used for loading DOS or Windows.}. 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 |
| (@pxref{Command-line interface}), or a menu interface (@pxref{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 |
| (@pxref{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 (@pxref{Naming convention}) to GRUB, how to |
| install GRUB on your drive (@pxref{Installation}), and how to boot your |
| OSes (@pxref{Booting}), step by step. |
| |
| |
| @node History |
| @section 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 |
| (@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot |
| Specification}), 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. @xref{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. |
| |
| |
| @node Changes from GRUB Legacy |
| @section Differences from previous versions |
| |
| GRUB 2 is a rewrite of GRUB (@pxref{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. |
| |
| @itemize @bullet |
| @item |
| The configuration file has a new name (@file{grub.cfg} rather than |
| @file{menu.lst} or @file{grub.conf}), new syntax (@pxref{Configuration}) and |
| many new commands (@pxref{Commands}). Configuration cannot be copied over |
| directly, although most GRUB Legacy users should not find the syntax too |
| surprising. |
| |
| @item |
| @file{grub.cfg} is typically automatically generated by |
| @command{grub-mkconfig} (@pxref{Simple configuration}). This makes it |
| easier to handle versioned kernel upgrades. |
| |
| @item |
| Partition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming |
| convention}). |
| |
| @item |
| The configuration file is now written in something closer to a full |
| scripting language: variables, conditionals, and loops are available. |
| |
| @item |
| A small amount of persistent storage is available across reboots, using the |
| @command{save_env} and @command{load_env} commands in GRUB and the |
| @command{grub-editenv} utility. This is not available in all configurations |
| (@pxref{Environment block}). |
| |
| @item |
| GRUB 2 has more reliable ways to find its own files and those of target |
| kernels on multiple-disk systems, and has commands (@pxref{search}) to find |
| devices using file system labels or Universally Unique Identifiers (UUIDs). |
| |
| @item |
| 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. |
| |
| @item |
| Many more file systems are supported, including but not limited to ext4, |
| HFS+, and NTFS. |
| |
| @item |
| GRUB 2 can read files directly from LVM and RAID devices. |
| |
| @item |
| A graphical terminal and a graphical menu system are available. |
| |
| @item |
| GRUB 2's interface can be translated, including menu entry names. |
| |
| @item |
| The image files (@pxref{Images}) that make up GRUB have been reorganised; |
| Stage 1, Stage 1.5, and Stage 2 are no more. |
| |
| @item |
| 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. |
| @end itemize |
| |
| |
| @node Features |
| @section GRUB features |
| |
| The primary requirement for GRUB is that it be compliant with the |
| @dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot |
| Specification, Motivation, multiboot, The Multiboot Specification}. |
| |
| The other goals, listed in approximate order of importance, are: |
| |
| @itemize @bullet{} |
| @item |
| Basic functions must be straightforward for end-users. |
| |
| @item |
| Rich functionality to support kernel experts and designers. |
| |
| @item |
| 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. |
| @end itemize |
| |
| Except for specific compatibility modes (chain-loading and the Linux |
| @dfn{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): |
| |
| @table @asis |
| @item Recognize multiple executable formats |
| Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol |
| tables are also loaded. |
| |
| @item Support non-Multiboot kernels |
| Support many of the various free 32-bit kernels that lack Multiboot |
| compliance (primarily FreeBSD, NetBSD@footnote{The NetBSD/i386 kernel |
| is Multiboot-compliant, but lacks support for Multiboot modules.}, |
| OpenBSD, and Linux). Chain-loading of other boot loaders is also |
| supported. |
| |
| @item Load multiples modules |
| Fully support the Multiboot feature of loading multiple modules. |
| |
| @item 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 (@pxref{Commands}) are a superset of those supported on the |
| command-line. An example configuration file is provided in |
| @ref{Configuration}. |
| |
| @item 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. |
| |
| @item 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 (@pxref{Commands}) are a subset of those supported |
| for configuration files. Editing commands closely resembles the Bash |
| command-line (@pxref{Command Line Editing, Bash, Command Line Editing, |
| features, Bash Features}), with @key{TAB}-completion of commands, |
| devices, partitions, and files in a directory depending on context. |
| |
| @item Support multiple filesystem types |
| Support multiple filesystem types transparently, plus a useful explicit |
| blocklist notation. The currently supported filesystem types are @dfn{Amiga |
| Fast FileSystem (AFFS)}, @dfn{AtheOS fs}, @dfn{BeFS}, |
| @dfn{BtrFS} (including raid0, raid1, raid10, gzip and lzo), |
| @dfn{cpio} (little- and big-endian bin, odc and newc variants), |
| @dfn{Linux ext2/ext3/ext4}, @dfn{DOS FAT12/FAT16/FAT32}, @dfn{exFAT}, @dfn{HFS}, |
| @dfn{HFS+}, @dfn{ISO9660} (including Joliet, Rock-ridge and multi-chunk files), |
| @dfn{JFS}, @dfn{Minix fs} (versions 1, 2 and 3), @dfn{nilfs2}, |
| @dfn{NTFS} (including compression), @dfn{ReiserFS}, @dfn{ROMFS}, |
| @dfn{Amiga Smart FileSystem (SFS)}, @dfn{Squash4}, @dfn{tar}, @dfn{UDF}, |
| @dfn{BSD UFS/UFS2}, @dfn{XFS}, and @dfn{ZFS} (including lzjb, gzip, |
| zle, mirror, stripe, raidz1/2/3 and encryption in AES-CCM and AES-GCM). |
| @xref{Filesystem}, for more information. |
| |
| @item Support automatic decompression |
| Can decompress files which were compressed by @command{gzip} or |
| @command{xz}@footnote{Only CRC32 data integrity check is supported (xz default |
| is CRC64 so one should use --check=crc32 option). LZMA BCJ filters are |
| supported.}. 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.@footnote{There are a few |
| pathological cases where loading a very badly organized ELF kernel might |
| take longer, but in practice this never happen.} |
| |
| 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. |
| |
| @item 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. |
| |
| @item 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. |
| |
| @item Detect all installed @sc{ram} |
| GRUB can generally find all the installed @sc{ram} on a PC-compatible |
| machine. It uses an advanced BIOS query technique for finding all |
| memory regions. As described on the Multiboot Specification (@pxref{Top, |
| Multiboot Specification, Motivation, multiboot, The Multiboot |
| Specification}), not all kernels make use of this information, but GRUB |
| provides it for those who do. |
| |
| @item Support Logical Block Address mode |
| In traditional disk calls (called @dfn{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 (@dfn{LBA}) mode. GRUB |
| automatically detects if LBA mode is available and uses it if |
| available. In LBA mode, GRUB can access the entire disk. |
| |
| @item 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 @dfn{TFTP} |
| protocol. |
| |
| @item 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. |
| @end table |
| |
| |
| @node Role of a boot loader |
| @section The role of a boot loader |
| |
| The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: |
| |
| @quotation |
| 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 |
| @emph{boot loader} is the most important software of all. I used to |
| refer to the above systems as either ``LILO''@footnote{The LInux LOader, |
| a boot loader that everybody uses, but nobody likes.} 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@dots{} GRUB! |
| @end quotation |
| |
| 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. |
| |
| |
| @node Naming convention |
| @chapter 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: |
| |
| @example |
| (fd0) |
| @end example |
| |
| First of all, GRUB requires that the device name be enclosed with |
| @samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy |
| disk. The number @samp{0} is the drive number, which is counted from |
| @emph{zero}. This expression means that GRUB will use the whole floppy |
| disk. |
| |
| @example |
| (hd0,msdos2) |
| @end example |
| |
| Here, @samp{hd} means it is a hard disk drive. The first integer |
| @samp{0} indicates the drive number, that is, the first hard disk, |
| the string @samp{msdos} indicates the partition scheme, while |
| the second integer, @samp{2}, indicates the partition number (or the |
| @sc{pc} slice number in the BSD terminology). The partition numbers are |
| counted from @emph{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. |
| |
| @example |
| (hd0,msdos5) |
| @end example |
| |
| This specifies the first @dfn{extended partition} of the first hard disk |
| drive. Note that the partition numbers for extended partitions are |
| counted from @samp{5}, regardless of the actual number of primary |
| partitions on your hard disk. |
| |
| @example |
| (hd1,msdos1,bsd1) |
| @end example |
| |
| This means the BSD @samp{a} partition on first @sc{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 @samp{set |
| root=(fd0)} or @samp{parttool (hd0,msdos3) hidden-}. To help you find out |
| which number specifies a partition you want, the GRUB command-line |
| (@pxref{Command-line interface}) options have argument |
| completion. This means that, for example, you only need to type |
| |
| @example |
| set root=( |
| @end example |
| |
| followed by a @key{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 @emph{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: |
| |
| @example |
| (hd0,msdos1)/vmlinuz |
| @end example |
| |
| This specifies the file named @samp{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. |
| |
| @node OS-specific notes about grub tools |
| @chapter OS-specific notes about grub tools |
| |
| On OS which have device nodes similar to Unix-like OS GRUB tools use the |
| OS name. E.g. for GNU/Linux: |
| |
| @example |
| # @kbd{grub-install /dev/sda} |
| @end example |
| |
| On AROS we use another syntax. For volumes: |
| |
| @example |
| //:<volume name> |
| @end example |
| |
| E.g. |
| |
| @example |
| //:DH0 |
| @end example |
| |
| For disks we use syntax: |
| @example |
| //:<driver name>/unit/flags |
| @end example |
| |
| E.g. |
| |
| @example |
| # @kbd{grub-install //:ata.device/0/0} |
| @end example |
| |
| On Windows we use UNC path. For volumes it's typically |
| |
| @example |
| \\?\Volume@{<GUID>@} |
| \\?\<drive letter>: |
| @end example |
| |
| E.g. |
| |
| @example |
| \\?\Volume@{17f34d50-cf64-4b02-800e-51d79c3aa2ff@} |
| \\?\C: |
| @end example |
| |
| |
| For disks it's |
| |
| @example |
| \\?\PhysicalDrive<number> |
| @end example |
| |
| E.g. |
| |
| @example |
| # @kbd{grub-install \\?\PhysicalDrive0} |
| @end example |
| |
| Beware that you may need to further escape the backslashes depending on your |
| shell. |
| |
| When compiled with cygwin support then cygwin drive names are automatically |
| when needed. E.g. |
| |
| @example |
| # @kbd{grub-install /dev/sda} |
| @end example |
| |
| @node Installation |
| @chapter 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 (@pxref{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 |
| @command{grub-install} (@pxref{Invoking grub-install}) on a UNIX-like OS. |
| |
| GRUB comes with boot images, which are normally put in the directory |
| @file{/usr/lib/grub/<cpu>-<platform>} (for BIOS-based machines |
| @file{/usr/lib/grub/i386-pc}). Hereafter, the directory where GRUB images are |
| initially placed (normally @file{/usr/lib/grub/<cpu>-<platform>}) will be |
| called the @dfn{image directory}, and the directory where the boot |
| loader needs to find them (usually @file{/boot}) will be called |
| the @dfn{boot directory}. |
| |
| @menu |
| * Installing GRUB using grub-install:: |
| * Making a GRUB bootable CD-ROM:: |
| * Device map:: |
| * BIOS installation:: |
| @end menu |
| |
| |
| @node Installing GRUB using grub-install |
| @section Installing GRUB using grub-install |
| |
| For information on where GRUB should be installed on PC BIOS platforms, |
| @pxref{BIOS installation}. |
| |
| In order to install GRUB under a UNIX-like OS (such |
| as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking |
| grub-install}) as the superuser (@dfn{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 @samp{/dev/hda}). |
| For example, under Linux the following will install GRUB into the MBR |
| of the first IDE disk: |
| |
| @example |
| # @kbd{grub-install /dev/sda} |
| @end example |
| |
| Likewise, under GNU/Hurd, this has the same effect: |
| |
| @example |
| # @kbd{grub-install /dev/hd0} |
| @end example |
| |
| But all the above examples assume that GRUB should put images under |
| the @file{/boot} directory. If you want GRUB to put images under a directory |
| other than @file{/boot}, you need to specify the option |
| @option{--boot-directory}. The typical usage is that you create a GRUB |
| boot floppy with a filesystem. Here is an example: |
| |
| @example |
| @group |
| # @kbd{mke2fs /dev/fd0} |
| # @kbd{mount -t ext2 /dev/fd0 /mnt} |
| # @kbd{mkdir /mnt/boot} |
| # @kbd{grub-install --boot-directory=/mnt/boot /dev/fd0} |
| # @kbd{umount /mnt} |
| @end group |
| @end example |
| |
| 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: |
| |
| @example |
| # @kbd{losetup /dev/loop0 /dev/sdb1} |
| # @kbd{mount /dev/loop0 /mnt/usb} |
| # @kbd{grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0} |
| @end example |
| |
| This install doesn't conflict with standard install as long as they are in |
| separate directories. |
| |
| Note that @command{grub-install} is actually just a shell script and the |
| real task is done by other tools such as @command{grub-mkimage}. Therefore, |
| you may run those commands directly to install GRUB, without using |
| @command{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. |
| |
| On EFI systems for fixed disk install you have to mount EFI System Partition. |
| If you mount it at @file{/boot/efi} then you don't need any special arguments: |
| |
| @example |
| # @kbd{grub-install} |
| @end example |
| |
| Otherwise you need to specify where your EFI System partition is mounted: |
| |
| @example |
| # @kbd{grub-install --efi-directory=/mnt/efi} |
| @end example |
| |
| For removable installs you have to use @option{--removable} and specify both |
| @option{--boot-directory} and @option{--efi-directory}: |
| |
| @example |
| # @kbd{grub-install --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable} |
| @end example |
| |
| @node Making a GRUB bootable CD-ROM |
| @section Making a GRUB bootable CD-ROM |
| |
| GRUB supports the @dfn{no emulation mode} in the El Torito |
| specification@footnote{El Torito is a specification for bootable CD |
| using BIOS functions.}. 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 |
| @file{cdboot.img}, which is concatenated with @file{core.img}. The |
| @file{core.img} used for this should be built with at least the |
| @samp{iso9660} and @samp{biosdisk} modules. Your bootable CD-ROM will |
| usually also need to include a configuration file @file{grub.cfg} and some |
| other GRUB modules. |
| |
| To make a simple generic GRUB rescue CD, you can use the |
| @command{grub-mkrescue} program (@pxref{Invoking grub-mkrescue}): |
| |
| @example |
| $ @kbd{grub-mkrescue -o grub.iso} |
| @end example |
| |
| You will often need to include other files in your image. To do this, first |
| make a top directory for the bootable image, say, @samp{iso}: |
| |
| @example |
| $ @kbd{mkdir iso} |
| @end example |
| |
| Make a directory for GRUB: |
| |
| @example |
| $ @kbd{mkdir -p iso/boot/grub} |
| @end example |
| |
| If desired, make the config file @file{grub.cfg} under @file{iso/boot/grub} |
| (@pxref{Configuration}), and copy any files and directories for the disc to the |
| directory @file{iso/}. |
| |
| Finally, make the image: |
| |
| @example |
| $ @kbd{grub-mkrescue -o grub.iso iso} |
| @end example |
| |
| This produces a file named @file{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 |
| @file{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. |
| |
| |
| @node Device map |
| @section The map between BIOS drives and OS devices |
| |
| If the device map file exists, the GRUB utilities (@command{grub-probe}, |
| etc.) read it to map BIOS drives to OS devices. This file consists of lines |
| like this: |
| |
| @example |
| (@var{device}) @var{file} |
| @end example |
| |
| @var{device} is a drive specified in the GRUB syntax (@pxref{Device |
| syntax}), and @var{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 (@file{/dev/hd*} versus @file{/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 @file{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 @samp{#}. |
| |
| |
| @node BIOS installation |
| @section BIOS installation |
| |
| @heading 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 @file{/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. |
| |
| @heading 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: |
| |
| @example |
| # @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on} |
| @end example |
| |
| If you are using gdisk, set the partition type to @samp{0xEF02}. With |
| partitioning programs that require setting the GUID directly, it should be |
| @samp{21686148-6449-6e6f-744e656564454649}. |
| |
| @strong{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. |
| |
| |
| @node Booting |
| @chapter 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 |
| @end menu |
| |
| |
| @node General boot methods |
| @section 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:: |
| @end menu |
| |
| |
| @node Loading an operating system directly |
| @subsection How to boot an OS directly with GRUB |
| |
| Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot, |
| The Multiboot Specification}) 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 (@pxref{Chain-loading}). |
| |
| FIXME: this section is incomplete. |
| |
| @enumerate |
| @item |
| Run the command @command{boot} (@pxref{boot}). |
| @end enumerate |
| |
| However, DOS and Windows have some deficiencies, so you might have to |
| use more complicated instructions. @xref{DOS/Windows}, for more |
| information. |
| |
| |
| @node Chain-loading |
| @subsection 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 @command{chainloader} command (@pxref{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: |
| |
| @verbatim |
| menuentry "Windows" { |
| insmod chain |
| insmod ntfs |
| set root=(hd0,1) |
| chainloader +1 |
| } |
| @end verbatim |
| @c FIXME: document UUIDs. |
| |
| On systems with multiple hard disks, an additional workaround may be |
| required. @xref{DOS/Windows}. |
| |
| Chain-loading is only supported on PC BIOS and EFI platforms. |
| |
| @node Loopback booting |
| @section 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 @pxref{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 @command{kfreebsd_module}, @command{knetbsd_module_elf}, |
| @command{kopenbsd_ramdisk}, @command{initrd} (@pxref{initrd}), |
| @command{initrd16} (@pxref{initrd}), @command{multiboot_module}, |
| @command{multiboot2_module} or @command{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 |
| |
| @node OS-specific notes |
| @section Some caveats on OS-specific issues |
| |
| Here, we describe some caveats on several operating systems. |
| |
| @menu |
| * GNU/Hurd:: |
| * GNU/Linux:: |
| * NetBSD:: |
| * DOS/Windows:: |
| @end menu |
| |
| |
| @node GNU/Hurd |
| @subsection 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. |
| |
| @enumerate |
| @item |
| Set GRUB's root device to the same drive as GNU/Hurd's. The command |
| @code{search --set=root --file /boot/gnumach.gz} or similar may help you |
| (@pxref{search}). |
| |
| @item |
| Load the kernel and the modules, like this: |
| |
| @example |
| @group |
| grub> @kbd{multiboot /boot/gnumach.gz root=device:hd0s1} |
| grub> @kbd{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> @kbd{module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)'} |
| @end group |
| @end example |
| |
| @item |
| Finally, run the command @command{boot} (@pxref{boot}). |
| @end enumerate |
| |
| |
| @node GNU/Linux |
| @subsection GNU/Linux |
| |
| It is relatively easy to boot GNU/Linux from GRUB, because it somewhat |
| resembles to boot a Multiboot-compliant OS. |
| |
| @enumerate |
| @item |
| Set GRUB's root device to the same drive as GNU/Linux's. The command |
| @code{search --set=root --file /vmlinuz} or similar may help you |
| (@pxref{search}). |
| |
| @item |
| Load the kernel using the command @command{linux} (@pxref{linux}): |
| |
| @example |
| grub> @kbd{linux /vmlinuz root=/dev/sda1} |
| @end example |
| |
| If you need to specify some kernel parameters, just append them to the |
| command. For example, to set @option{acpi} to @samp{off}, do this: |
| |
| @example |
| grub> @kbd{linux /vmlinuz root=/dev/sda1 acpi=off} |
| @end example |
| |
| See the documentation in the Linux source tree for complete information on |
| the available options. |
| |
| With @command{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 |
| @command{linux16} |
| |
| @example |
| grub> @kbd{linux16 /vmlinuz root=/dev/sda1 acpi=off} |
| @end example |
| |
| @item |
| If you use an initrd, execute the command @command{initrd} (@pxref{initrd}) |
| after @command{linux}: |
| |
| @example |
| grub> @kbd{initrd /initrd} |
| @end example |
| |
| If you used @command{linux16} you need to use @command{initrd16}: |
| |
| @example |
| grub> @kbd{initrd16 /initrd} |
| @end example |
| |
| @item |
| Finally, run the command @command{boot} (@pxref{boot}). |
| @end enumerate |
| |
| @strong{Caution:} If you use an initrd and specify the @samp{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 @command{uppermem} @emph{before} loading the |
| kernel. @xref{uppermem}, for more information. |
| |
| |
| @node NetBSD |
| @subsection NetBSD |
| |
| Booting a NetBSD kernel from GRUB is also relatively easy: first set |
| GRUB's root device, then load the kernel and the modules, and finally |
| run @command{boot}. |
| |
| @enumerate |
| @item |
| Set GRUB's root device to the partition holding the NetBSD root file |
| system. For a disk with a NetBSD disk label, this is usually the first |
| partition (a:). In that case, and assuming that the partition is on the |
| first hard disk, set GRUB's root device as follows: |
| |
| @example |
| grub> @kbd{insmod part_bsd} |
| grub> @kbd{set root=(hd0,netbsd1)} |
| @end example |
| |
| For a disk with a GUID Partition Table (GPT), and assuming that the |
| NetBSD root partition is the third GPT partition, do this: |
| |
| @example |
| grub> @kbd{insmod part_gpt} |
| grub> @kbd{set root=(hd0,gpt3)} |
| @end example |
| |
| @item |
| Load the kernel using the command @command{knetbsd}: |
| |
| @example |
| grub> @kbd{knetbsd /netbsd} |
| @end example |
| |
| Various options may be given to @command{knetbsd}. These options are, |
| for the most part, the same as in the NetBSD boot loader. For instance, |
| to boot the system in single-user mode and with verbose messages, do |
| this: |
| |
| @example |
| grub> @kbd{knetbsd /netbsd -s -v} |
| @end example |
| |
| @item |
| If needed, load kernel modules with the command |
| @command{knetbsd_module_elf}. A typical example is the module for the |
| root file system: |
| |
| @example |
| grub> @kbd{knetbsd_module_elf /stand/amd64/6.0/modules/ffs/ffs.kmod} |
| @end example |
| |
| @item |
| Finally, run the command @command{boot} (@pxref{boot}). |
| @end enumerate |
| |
| |
| @node DOS/Windows |
| @subsection DOS/Windows |
| |
| GRUB cannot boot DOS or Windows directly, so you must chain-load them |
| (@pxref{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 @command{drivemap} (@pxref{drivemap}), like this: |
| |
| @example |
| drivemap -s (hd0) (hd1) |
| @end example |
| |
| This performs a @dfn{virtual} swap between your first and second hard |
| drive. |
| |
| @strong{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 @dfn{hides} a DOS (or Windows) partition (@pxref{parttool}), DOS (or |
| Windows) will ignore the partition. If GRUB @dfn{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: |
| |
| @example |
| @group |
| parttool (hd0,1) hidden- |
| parttool (hd0,2) hidden+ |
| set root=(hd0,1) |
| chainloader +1 |
| parttool @verb{'${root}'} boot+ |
| boot |
| @end group |
| @end example |
| |
| |
| @node Configuration |
| @chapter Writing your own configuration file |
| |
| GRUB is configured using @file{grub.cfg}, usually located under |
| @file{/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 |
| @end menu |
| |
| |
| @node Simple configuration |
| @section Simple configuration handling |
| |
| The program @command{grub-mkconfig} (@pxref{Invoking grub-mkconfig}) |
| generates @file{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. |
| |
| @command{grub-mkconfig} does have some limitations. While adding extra |
| custom menu entries to the end of the list can be done by editing |
| @file{/etc/grub.d/40_custom} or creating @file{/boot/grub/custom.cfg}, |
| changing the order of menu entries or changing their titles may require |
| making complex changes to shell scripts stored in @file{/etc/grub.d/}. This |
| may be improved in the future. In the meantime, those who feel that it |
| would be easier to write @file{grub.cfg} directly are encouraged to do so |
| (@pxref{Booting}, and @ref{Shell-like scripting}), and to disable any system |
| provided by their distribution to automatically run @command{grub-mkconfig}. |
| |
| The file @file{/etc/default/grub} controls the operation of |
| @command{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 |
| @samp{KEY=value} lines, but if the value contains spaces or other special |
| characters then it must be quoted. For example: |
| |
| @example |
| GRUB_TERMINAL_INPUT="console serial" |
| @end example |
| |
| Valid keys in @file{/etc/default/grub} are as follows: |
| |
| @table @samp |
| @item 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 @samp{saved}. Using the id 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: |
| |
| @verbatim |
| menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux { |
| ... |
| } |
| @end verbatim |
| |
| then you can make this the default using: |
| |
| @example |
| GRUB_DEFAULT=example-gnu-linux |
| @end example |
| |
| Previously it was documented the way to use entry title. While this still |
| works it's not recommended since titles often contain unstable device names |
| and may be translated |
| |
| If you set this to @samp{saved}, then the default menu entry will be that |
| saved by @samp{GRUB_SAVEDEFAULT} or @command{grub-set-default}. This relies on |
| the environment block, which may not be available in all situations |
| (@pxref{Environment block}). |
| |
| The default is @samp{0}. |
| |
| @item GRUB_SAVEDEFAULT |
| If this option is set to @samp{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 @samp{GRUB_DEFAULT=saved}; it is a separate option because |
| @samp{GRUB_DEFAULT=saved} is useful without this option, in conjunction with |
| @command{grub-set-default}. Unset by default. |
| This option relies on the environment block, which may not be available in |
| all situations (@pxref{Environment block}). |
| |
| @item GRUB_TIMEOUT |
| Boot the default entry this many seconds after the menu is displayed, unless |
| a key is pressed. The default is @samp{5}. Set to @samp{0} to boot |
| immediately without displaying the menu, or to @samp{-1} to wait |
| indefinitely. |
| |
| If @samp{GRUB_TIMEOUT_STYLE} is set to @samp{countdown} or @samp{hidden}, |
| the timeout is instead counted before the menu is displayed. |
| |
| @item GRUB_TIMEOUT_STYLE |
| If this option is unset or set to @samp{menu}, then GRUB will display the |
| menu and then wait for the timeout set by @samp{GRUB_TIMEOUT} to expire |
| before booting the default entry. Pressing a key interrupts the timeout. |
| |
| If this option is set to @samp{countdown} or @samp{hidden}, then, before |
| displaying the menu, GRUB will wait for the timeout set by |
| @samp{GRUB_TIMEOUT} to expire. If @key{ESC} is pressed during that time, it |
| will display the menu and wait for input. If a hotkey associated with a |
| menu entry is pressed, it will boot the associated menu entry immediately. |
| If the timeout expires before either of these happens, it will boot the |
| default entry. In the @samp{countdown} case, it will show a one-line |
| indication of the remaining time. |
| |
| @item GRUB_DEFAULT_BUTTON |
| @itemx GRUB_TIMEOUT_BUTTON |
| @itemx GRUB_TIMEOUT_STYLE_BUTTON |
| @itemx GRUB_BUTTON_CMOS_ADDRESS |
| Variants of the corresponding variables without the @samp{_BUTTON} suffix, |
| used to support vendor-specific power buttons. @xref{Vendor power-on keys}. |
| |
| @item GRUB_DISTRIBUTOR |
| Set by distributors of GRUB to their identifying name. This is used to |
| generate more informative menu entry titles. |
| |
| @item 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 |
| @samp{console} (native platform console), @samp{serial} (serial terminal), |
| @samp{serial_<port>} (serial terminal with explicit port selection), |
| @samp{at_keyboard} (PC AT keyboard), or @samp{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. |
| |
| @item 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 |
| @samp{console} (native platform console), @samp{serial} (serial terminal), |
| @samp{serial_<port>} (serial terminal with explicit port selection), |
| @samp{gfxterm} (graphics-mode output), @samp{vga_text} (VGA text output), |
| @samp{mda_text} (MDA text output), @samp{morse} (Morse-coding using system |
| beeper) or @samp{spkmodem} (simple data protocol using system speaker). |
| |
| @samp{spkmodem} is useful when no serial port is available. Connect the output |
| of sending system (where GRUB is running) to line-in of receiving system |
| (usually developer machine). |
| On receiving system compile @samp{spkmodem-recv} from |
| @samp{util/spkmodem-recv.c} and run: |
| |
| @example |
| parecord --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv |
| @end example |
| |
| The default is to use the platform's native terminal output. |
| |
| @item GRUB_TERMINAL |
| If this option is set, it overrides both @samp{GRUB_TERMINAL_INPUT} and |
| @samp{GRUB_TERMINAL_OUTPUT} to the same value. |
| |
| @item GRUB_SERIAL_COMMAND |
| A command to configure the serial port when using the serial console. |
| @xref{serial}. Defaults to @samp{serial}. |
| |
| @item GRUB_CMDLINE_LINUX |
| Command-line arguments to add to menu entries for the Linux kernel. |
| |
| @item GRUB_CMDLINE_LINUX_DEFAULT |
| Unless @samp{GRUB_DISABLE_RECOVERY} is set to @samp{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 |
| @samp{GRUB_CMDLINE_LINUX}. |
| |
| @item GRUB_CMDLINE_NETBSD |
| @itemx GRUB_CMDLINE_NETBSD_DEFAULT |
| As @samp{GRUB_CMDLINE_LINUX} and @samp{GRUB_CMDLINE_LINUX_DEFAULT}, but for |
| NetBSD. |
| |
| @item GRUB_CMDLINE_GNUMACH |
| As @samp{GRUB_CMDLINE_LINUX}, but for GNU Mach. |
| |
| @item GRUB_CMDLINE_XEN |
| @itemx GRUB_CMDLINE_XEN_DEFAULT |
| The values of these options are passed to Xen hypervisor Xen menu entries, |
| for all respectively normal entries. |
| |
| @item GRUB_CMDLINE_LINUX_XEN_REPLACE |
| @item GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT |
| The values of these options replace the values of @samp{GRUB_CMDLINE_LINUX} |
| and @samp{GRUB_CMDLINE_LINUX_DEFAULT} for Linux and Xen menu entries. |
| |
| @item GRUB_DISABLE_LINUX_UUID |
| Normally, @command{grub-mkconfig} will generate menu entries that use |
| universally-unique identifiers (UUIDs) to identify the root filesystem to |
| the Linux kernel, using a @samp{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 @samp{true}. |
| |
| @item GRUB_DISABLE_RECOVERY |
| If this option is set to @samp{true}, disable the generation of recovery |
| mode menu entries. |
| |
| @item GRUB_VIDEO_BACKEND |
| If graphical video support is required, either because the @samp{gfxterm} |
| graphical terminal is in use or because @samp{GRUB_GFXPAYLOAD_LINUX} is set, |
| then @command{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 @command{grub-install} has been run, the available video drivers are |
| listed in @file{/boot/grub/video.lst}. |
| |
| @item GRUB_GFXMODE |
| Set the resolution used on the @samp{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 @samp{auto}, which tries to select a preferred |
| resolution. @xref{gfxmode}. |
| |
| @item GRUB_BACKGROUND |
| Set a background image for use with the @samp{gfxterm} graphical terminal. |
| The value of this option must be a file readable by GRUB at boot time, and |
| it must end with @file{.png}, @file{.tga}, @file{.jpg}, or @file{.jpeg}. |
| The image will be scaled if necessary to fit the screen. |
| |
| @item GRUB_THEME |
| Set a theme for use with the @samp{gfxterm} graphical terminal. |
| |
| @item GRUB_GFXPAYLOAD_LINUX |
| Set to @samp{text} to force the Linux kernel to boot in normal text mode, |
| @samp{keep} to preserve the graphics mode set using @samp{GRUB_GFXMODE}, |
| @samp{@var{width}x@var{height}}[@samp{x@var{depth}}] to set a particular |
| graphics mode, or a sequence of these separated by commas or semicolons to |
| try several modes in sequence. @xref{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 @samp{text} and |
| GRUB will tell Linux to boot in normal text mode. |
| |
| @item GRUB_DISABLE_OS_PROBER |
| Normally, @command{grub-mkconfig} will try to use the external |
| @command{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 @samp{true} to disable this. |
| |
| @item GRUB_OS_PROBER_SKIP_LIST |
| List of space-separated FS UUIDs of filesystems to be ignored from os-prober |
| output. For efi chainloaders it's <UUID>@@<EFI FILE> |
| |
| @item GRUB_DISABLE_SUBMENU |
| Normally, @command{grub-mkconfig} will generate top level menu entry for |
| the kernel with highest version number and put all other found kernels |
| or alternative menu entries for recovery mode in submenu. For entries returned |
| by @command{os-prober} first entry will be put on top level and all others |
| in submenu. If this option is set to @samp{y}, flat menu with all entries |
| on top level will be generated instead. Changing this option will require |
| changing existing values of @samp{GRUB_DEFAULT}, @samp{fallback} (@pxref{fallback}) |
| and @samp{default} (@pxref{default}) environment variables as well as saved |
| default entry using @command{grub-set-default} and value used with |
| @command{grub-reboot}. |
| |
| @item GRUB_ENABLE_CRYPTODISK |
| If set to @samp{y}, @command{grub-mkconfig} and @command{grub-install} will |
| check for encrypted disks and generate additional commands needed to access |
| them during boot. Note that in this case unattended boot is not possible |
| because GRUB will wait for passphrase to unlock encrypted container. |
| |
| @item 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 @ref{play}. |
| |
| @item GRUB_BADRAM |
| If this option is set, GRUB will issue a @ref{badram} command to filter |
| out specified regions of RAM. |
| |
| @item 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 |
| @file{grub.cfg}. |
| |
| @end table |
| |
| The following options are still accepted for compatibility with existing |
| configurations, but have better replacements: |
| |
| @table @samp |
| @item GRUB_HIDDEN_TIMEOUT |
| Wait this many seconds before displaying the menu. If @key{ESC} is pressed |
| during that time, display the menu and wait for input according to |
| @samp{GRUB_TIMEOUT}. If a hotkey associated with a menu entry is pressed, |
| boot the associated menu entry immediately. If the timeout expires before |
| either of these happens, display the menu for the number of seconds |
| specified in @samp{GRUB_TIMEOUT} before booting the default entry. |
| |
| If you set @samp{GRUB_HIDDEN_TIMEOUT}, you should also set |
| @samp{GRUB_TIMEOUT=0} so that the menu is not displayed at all unless |
| @key{ESC} is pressed. |
| |
| This option is unset by default, and is deprecated in favour of the less |
| confusing @samp{GRUB_TIMEOUT_STYLE=countdown} or |
| @samp{GRUB_TIMEOUT_STYLE=hidden}. |
| |
| @item GRUB_HIDDEN_TIMEOUT_QUIET |
| In conjunction with @samp{GRUB_HIDDEN_TIMEOUT}, set this to @samp{true} to |
| suppress the verbose countdown while waiting for a key to be pressed before |
| displaying the menu. |
| |
| This option is unset by default, and is deprecated in favour of the less |
| confusing @samp{GRUB_TIMEOUT_STYLE=countdown}. |
| |
| @item GRUB_HIDDEN_TIMEOUT_BUTTON |
| Variant of @samp{GRUB_HIDDEN_TIMEOUT}, used to support vendor-specific power |
| buttons. @xref{Vendor power-on keys}. |
| |
| This option is unset by default, and is deprecated in favour of the less |
| confusing @samp{GRUB_TIMEOUT_STYLE=countdown} or |
| @samp{GRUB_TIMEOUT_STYLE=hidden}. |
| |
| @end table |
| |
| For more detailed customisation of @command{grub-mkconfig}'s output, you may |
| edit the scripts in @file{/etc/grub.d} directly. |
| @file{/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. |
| |
| |
| @node Shell-like scripting |
| @section Writing full configuration files directly |
| |
| @c Some of this section is derived from the GNU Bash manual page, also |
| @c copyrighted by the FSF. |
| |
| @file{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. |
| |
| @heading Words |
| |
| A @dfn{word} is a sequence of characters considered as a single unit by |
| GRUB. Words are separated by @dfn{metacharacters}, which are the following |
| plus space, tab, and newline: |
| |
| @example |
| @{ @} | & $ ; < > |
| @end example |
| |
| Quoting may be used to include metacharacters in words; see below. |
| |
| @heading 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 @code{for} command: |
| |
| @example |
| ! [[ ]] @{ @} |
| case do done elif else esac fi for function |
| if in menuentry select then time until while |
| @end example |
| |
| Not all of these reserved words have a useful purpose yet; some are reserved |
| for future expansion. |
| |
| @heading 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 @dfn{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 @samp{$} and @samp{\}. |
| The @samp{$} character retains its special meaning within double quotes. |
| The backslash retains its special meaning only when followed by one of the |
| following characters: @samp{$}, @samp{"}, @samp{\}, or newline. A |
| backslash-newline pair is treated as a line continuation (that is, it is |
| removed from the input stream and effectively ignored@footnote{Currently a |
| backslash-newline pair within a variable name is not handled properly, so |
| use this feature with some care.}). A double quote may be quoted within |
| double quotes by preceding it with a backslash. |
| |
| @heading Variable expansion |
| |
| The @samp{$} 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 (@pxref{Environment}). |
| |
| Positional variable names consist of one or more digits. They represent |
| parameters passed to function calls, with @samp{$1} representing the first |
| parameter, and so on. |
| |
| The special variable name @samp{?} expands to the exit status of the most |
| recently executed command. When positional variable names are active, other |
| special variable names @samp{@@}, @samp{*} and @samp{#} are defined and they |
| expand to all positional parameters with necessary quoting, positional |
| parameters without any quoting, and positional parameter count respectively. |
| |
| @heading Comments |
| |
| A word beginning with @samp{#} causes that word and all remaining characters |
| on that line to be ignored. |
| |
| @heading Simple commands |
| |
| A @dfn{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 @code{!} precedes the command, then the return value is instead the |
| logical negation of the command's exit status. |
| |
| @heading Compound commands |
| |
| A @dfn{compound command} is one of the following: |
| |
| @table @asis |
| @item for @var{name} in @var{word} @dots{}; do @var{list}; done |
| The list of words following @code{in} is expanded, generating a list of |
| items. The variable @var{name} is set to each element of this list in turn, |
| and @var{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 |
| @code{in} results in an empty list, no commands are executed, and the return |
| status is 0. |
| |
| @item if @var{list}; then @var{list}; [elif @var{list}; then @var{list};] @dots{} [else @var{list};] fi |
| The @code{if} @var{list} is executed. If its exit status is zero, the |
| @code{then} @var{list} is executed. Otherwise, each @code{elif} @var{list} |
| is executed in turn, and if its exit status is zero, the corresponding |
| @code{then} @var{list} is executed and the command completes. Otherwise, |
| the @code{else} @var{list} is executed, if present. The exit status is the |
| exit status of the last command executed, or zero if no condition tested |
| true. |
| |
| @item while @var{cond}; do @var{list}; done |
| @itemx until @var{cond}; do @var{list}; done |
| The @code{while} command continuously executes the @code{do} @var{list} as |
| long as the last command in @var{cond} returns an exit status of zero. The |
| @code{until} command is identical to the @code{while} command, except that |
| the test is negated; the @code{do} @var{list} is executed as long as the |
| last command in @var{cond} returns a non-zero exit status. The exit status |
| of the @code{while} and @code{until} commands is the exit status of the last |
| @code{do} @var{list} command executed, or zero if none was executed. |
| |
| @item function @var{name} @{ @var{command}; @dots{} @} |
| This defines a function named @var{name}. The @dfn{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 |
| @var{name} is specified as the name of a simple command. Function |
| definitions do not affect the exit status in @code{$?}. When executed, the |
| exit status of a function is the exit status of the last command executed in |
| the body. |
| |
| @item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @{ @var{command}; @dots{} @} |
| @xref{menuentry}. |
| @end table |
| |
| @heading 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. |
| |
| @table @asis |
| @item break [@code{n}] |
| Exit from within a @code{for}, @code{while}, or @code{until} loop. If |
| @code{n} is specified, break @code{n} levels. @code{n} must be greater than |
| or equal to 1. If @code{n} is greater than the number of enclosing loops, |
| all enclosing loops are exited. The return value is 0 unless @code{n} is |
| not greater than or equal to 1. |
| |
| @item continue [@code{n}] |
| Resume the next iteration of the enclosing @code{for}, @code{while} or |
| @code{until} loop. If @code{n} is specified, resume at the @code{n}th |
| enclosing loop. @code{n} must be greater than or equal to 1. If @code{n} |
| is greater than the number of enclosing loops, the last enclosing loop (the |
| @dfn{top-level} loop) is resumed. The return value is 0 unless @code{n} is |
| not greater than or equal to 1. |
| |
| @item return [@code{n}] |
| Causes a function to exit with the return value specified by @code{n}. If |
| @code{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. |
| |
| @item setparams [@code{arg}] @dots{} |
| Replace positional parameters starting with @code{$1} with arguments to |
| @command{setparams}. |
| |
| @item shift [@code{n}] |
| The positional parameters from @code{n}+1 @dots{} are renamed to |
| @code{$1}@dots{}. Parameters represented by the numbers @code{$#} down to |
| @code{$#}-@code{n}+1 are unset. @code{n} must be a non-negative number less |
| than or equal to @code{$#}. If @code{n} is 0, no parameters are changed. |
| If @code{n} is not given, it is assumed to be 1. If @code{n} is greater |
| than @code{$#}, the positional parameters are not changed. The return |
| status is greater than zero if @code{n} is greater than @code{$#} or less |
| than zero; otherwise 0. |
| |
| @end table |
| |
| @node Multi-boot manual config |
| @section 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: |
| |
| @code{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: |
| |
| @code{GRUB_DISABLE_OS_PROBER=true} |
| |
| in /etc/default/grub |
| |
| Then write a grub.cfg (/mnt/boot/grub/grub.cfg): |
| |
| @example |
| |
| 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 |
| @} |
| |
| @end example |
| |
| Notes: |
| @itemize |
| @item Argument to search after --label is FS LABEL. You can also use UUIDs with --fs-uuid UUID instead of --label LABEL. You could also use direct @code{root=hd0,msdosX} but this is not recommended due to device name instability. |
| @end itemize |
| |
| @node Embedded configuration |
| @section 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. |
| @command{grub-install} uses this feature when it is not using BIOS disk |
| functions or when installing to a different disk from the one containing |
| @file{/boot/grub}, in which case it needs to use the @command{search} |
| command (@pxref{search}) to find @file{/boot/grub}. |
| |
| To embed a configuration file, use the @option{-c} option to |
| @command{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 |
| @command{grub-mkimage}. |
| |
| After the embedded configuration file (if any) is executed, GRUB will load |
| the @samp{normal} module (@pxref{normal}), which will then read the real |
| configuration file from @file{$prefix/grub.cfg}. By this point, the |
| @code{root} variable will also have been set to the root device name. For |
| example, @code{prefix} might be set to @samp{(hd0,1)/boot/grub}, and |
| @code{root} might be set to @samp{hd0,1}. Thus, in most cases, the embedded |
| configuration file only needs to set the @code{prefix} and @code{root} |
| variables, and then drop through to GRUB's normal processing. A typical |
| example of this might look like this: |
| |
| @example |
| @group |
| search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root |
| set prefix=($root)/boot/grub |
| @end group |
| @end example |
| |
| (The @samp{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 @file{grub.cfg}, or reading files from a directory |
| other than that where GRUB's loadable modules are installed. To do this, |
| include the @samp{configfile} and @samp{normal} modules in the core image, |
| and embed a configuration file that uses the @command{configfile} command to |
| load another file. The following example of this also requires the |
| @command{echo}, @command{search_label}, and @command{test} modules to be |
| included in the core image: |
| |
| @example |
| @group |
| 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 |
| @end group |
| @end example |
| |
| The embedded configuration file may not contain menu entries directly, but |
| may only read them from elsewhere using @command{configfile}. |
| |
| @node Theme file format |
| @chapter Theme file format |
| @section 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 |
| |
| @section Theme Elements |
| @subsection Colors |
| |
| Colors can be specified in several ways: |
| |
| @itemize |
| @item HTML-style ``#RRGGBB'' or ``#RGB'' format, where *R*, *G*, and *B* are hexadecimal digits (e.g., ``#8899FF'') |
| @item as comma-separated decimal RGB values (e.g., ``128, 128, 255'') |
| @item with ``SVG 1.0 color names'' (e.g., ``cornflowerblue'') which must be specified in lowercase. |
| @end itemize |
| @subsection 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 (@ref{loadfont}). To see the list of |
| loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}). If there are too many fonts to |
| fit on screen, do ``set pager=1'' before executing ``lsfonts''. |
| |
| |
| @subsection Progress Bar |
| |
| @float Figure, Pixmap-styled progress bar |
| @c @image{Theme_progress_bar,,,,png} |
| @end float |
| |
| @float Figure, Plain progress bar, drawn with solid color. |
| @c @image{Theme_progress_bar_filled,,,,png} |
| @end float |
| |
| 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. |
| |
| @subsection Circular Progress Indicator |
| |
| @c @image{Theme_circular_progress,,,,.png} |
| |
| 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. |
| |
| |
| @subsection 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. |
| |
| |
| @subsection Boot Menu |
| |
| @c @image{Theme_boot_menu,,,,.png} |
| |
| 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. |
| |
| |
| @subsection 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: |
| |
| @multitable @columnfractions 0.3 0.3 0.3 |
| @item Northwest (nw) @tab North (n) @tab Northeast (ne) |
| @item West (w) @tab Center (c) @tab East (e) |
| @item Southwest (sw) @tab South (s) @tab Southeast (se) |
| @end multitable |
| |
| 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: |
| |
| @enumerate |
| @item The edge slices (north, south, east, and west) are scaled in the direction of the edge they are adjacent to. For instance, the west slice is scaled vertically. |
| @item The corner slices (northwest, northeast, southeast, and southwest) are not scaled. |
| @item The center slice is scaled to fill the remaining space in the middle. |
| @end enumerate |
| |
| As an example of how an image might be sliced up, consider the styled box |
| used for a terminal view. |
| |
| @float Figure, An example of the slices (in red) used for a terminal window. This drawing was created and sliced in Inkscape_, as the next section explains. |
| @c @image{Box_slice_example_terminal,,,,.png} |
| @end float |
| |
| @subsection 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: |
| |
| @enumerate |
| @item Create or open the drawing you'd like use. |
| @item Create a new layer on the top of the layer stack. Make it visible. Select this layer as the current layer. |
| @item Draw 9 rectangles on your drawing where you'd like the slices to be. Clear the fill option, and set the stroke to 1 pixel wide solid stroke. The corners of the slices must meet precisely; if it is off by a single pixel, it will probably be evident when the styled box is rendered in the GRUB menu. You should probably go to File | Document Properties | Grids and enable a grid or create a guide (click on one of the rulers next to the drawing and drag over the drawing; release the mouse button to place the guide) to help place the rectangles precisely. |
| @item Right click on the center slice rectangle and choose Object Properties. Change the "Id" to ``slice_c`` and click Set. Repeat this for the remaining 8 rectangles, giving them Id values of ``slice_n``, ``slice_ne``, ``slice_e``, and so on according to the location. |
| @item Save the drawing. |
| @item Select all the slice rectangles. With the slice layer selected, you can simply press Ctrl+A to select all rectangles. The status bar should indicate that 9 rectangles are selected. |
| @item Click the layer hide icon for the slice layer in the layer palette. The rectangles will remain selected, even though they are hidden. |
| @item Choose File | Export Bitmap and check the *Batch export 9 selected objects* box. Make sure that *Hide all except selected* is unchecked. click *Export*. This will create PNG files in the same directory as the drawing, named after the slices. These can now be used for a styled box in a GRUB theme. |
| @end enumerate |
| |
| @section 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: |
| @enumerate |
| @item Global properties. |
| @item Component construction. |
| @end enumerate |
| |
| @subsection Global Properties |
| |
| @subsection Format |
| |
| Global properties are specified with the simple format: |
| @itemize |
| @item name1: value1 |
| @item name2: "value which may contain spaces" |
| @item name3: #88F |
| @end itemize |
| |
| In this example, name3 is assigned a color value. |
| |
| |
| @subsection Global Property List |
| |
| @multitable @columnfractions 0.3 0.6 |
| @item title-text |
| @tab Specifies the text to display at the top center of the screen as a title. |
| @item title-font |
| @tab Defines the font used for the title message at the top of the screen. |
| @item title-color |
| @tab Defines the color of the title message. |
| @item message-font |
| @tab Currently unused. Left for backward compatibility. |
| @item message-color |
| @tab Currently unused. Left for backward compatibility. |
| @item message-bg-color |
| @tab Currently unused. Left for backward compatibility. |
| @item desktop-image |
| @tab Specifies the image to use as the background. It will be scaled |
| to fit the screen size or proportionally scaled depending on the scale |
| method. |
| @item desktop-image-scale-method |
| @tab Specifies the scaling method for the *desktop-image*. Options are |
| ``stretch``, ``crop``, ``padding``, ``fitwidth``, ``fitheight``. |
| ``stretch`` for fitting the screen size. Otherwise it is proportional |
| scaling of a part of *desktop-image* to the part of the screen. |
| ``crop`` part of the *desktop-image* will be proportionally scaled to |
| fit the screen sizes. ``padding`` the entire *desktop-image* will be |
| contained on the screen. ``fitwidth`` for fitting the *desktop-image*'s |
| width with screen width. ``fitheight`` for fitting the *desktop-image*'s |
| height with the screen height. Default is ``stretch``. |
| @item desktop-image-h-align |
| @tab Specifies the horizontal alignment of the *desktop-image* if |
| *desktop-image-scale-method* isn't equeal to ``stretch``. Options are |
| ``left``, ``center``, ``right``. Default is ``center``. |
| @item desktop-image-v-align |
| @tab Specifies the vertical alignment of the *desktop-image* if |
| *desktop-image-scale-method* isn't equeal to ``stretch``. Options are |
| ``top``, ``center``, ``bottom``. Default is ``center``. |
| @item desktop-color |
| @tab Specifies the color for the background if *desktop-image* is not |
| specified. |
| @item terminal-box |
| @tab Specifies the file name pattern for the styled box slices used for the |
| command line terminal window. For example, ``terminal-box: terminal_*.png`` |
| will use the images ``terminal_c.png`` as the center area, ``terminal_n.png`` |
| as the north (top) edge, ``terminal_nw.png`` as the northwest (upper left) |
| corner, and so on. If the image for any slice is not found, it will simply |
| be left empty. |
| @item terminal-border |
| @tab Specifies the border width of the terminal window. |
| @item terminal-left |
| @tab Specifies the left coordinate of the terminal window. |
| @item terminal-top |
| @tab Specifies the top coordinate of the terminal window. |
| @item terminal-width |
| @tab Specifies the width of the terminal window. |
| @item terminal-height |
| @tab Specifies the height of the terminal window. |
| @end multitable |
| |
| |
| @subsection 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: |
| |
| @code{ + 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: |
| @itemize |
| @item a single word (e.g., ``align = center``, ``color = #FF8080``), |
| @item a quoted string (e.g., ``text = "Hello, World!"``), or |
| @item a tuple (e.g., ``preferred_size = (120, 80)``). |
| @end itemize |
| |
| @subsection Component List |
| |
| The following is a list of the components and the properties they support. |
| |
| @itemize |
| @item label |
| A label displays a line of text. |
| |
| Properties: |
| @multitable @columnfractions 0.2 0.7 |
| @item id |
| @tab Set to ``__timeout__`` to display the time elapsed to an automatical |
| boot of the default entry. |
| @item text |
| @tab The text to display. If ``id`` is set to ``__timeout__`` and no |
| ``text`` property is set then the amount of seconds will be shown. |
| If set to ``@@KEYMAP_SHORT@@``, ``@@KEYMAP_MIDDLE@@`` or |
| ``@@KEYMAP_LONG@@`` then predefined hotkey information will be shown. |
| @item font |
| @tab The font to use for text display. |
| @item color |
| @tab The color of the text. |
| @item align |
| @tab The horizontal alignment of the text within the component. |
| Options are ``left``, ``center`` and ``right``. |
| @item visible |
| @tab Set to ``false`` to hide the label. |
| @end multitable |
| |
| @item image |
| A component that displays an image. The image is scaled to fit |
| the component. |
| |
| Properties: |
| |
| @multitable @columnfractions 0.2 0.7 |
| @item file |
| @tab The full path to the image file to load. |
| @end multitable |
| |
| @item 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: |
| |
| @multitable @columnfractions 0.2 0.7 |
| @item id |
| @tab Set to ``__timeout__`` to display the time elapsed to an automatical |
| boot of the default entry. |
| @item fg_color |
| @tab The foreground color for plain solid color rendering. |
| @item bg_color |
| @tab The background color for plain solid color rendering. |
| @item border_color |
| @tab The border color for plain solid color rendering. |
| @item text_color |
| @tab The text color. |
| @item bar_style |
| @tab The styled box specification for the frame of the progress bar. |
| Example: ``progress_frame_*.png`` |
| If the value is equal to ``highlight_style`` then no styled boxes |
| will be shown. |
| @item highlight_style |
| @tab The styled box specification for the highlighted region of the |
| progress bar. This box will be used to paint just the highlighted region |
| of the bar, and will be increased in size as the bar nears completion. |
| Example: ``progress_hl_*.png``. |
| If the value is equal to ``bar_style`` then no styled boxes |
| will be shown. |
| @item highlight_overlay |
| @tab If this option is set to ``true`` then the highlight box |
| side slices (every slice except the center slice) will overlay the |
| frame box side slices. And the center slice of the highlight box |
| can move all the way (from top to bottom), being drawn on the center |
| slice of the frame box. That way we can make a progress bar with |
| round-shaped edges so there won't be a free space from the highlight to |
| the frame in top and bottom scrollbar positions. Default is ``false``. |
| @item font |
| @tab The font to use for progress bar. |
| @item text |
| @tab The text to display on the progress bar. If the progress bar's ID |
| is set to ``__timeout__`` and the value of this property is set to |
| ``@@TIMEOUT_NOTIFICATION_SHORT@@``, ``@@TIMEOUT_NOTIFICATION_MIDDLE@@`` |
| or ``@@TIMEOUT_NOTIFICATION_LONG@@``, then GRUB will update this |
| property with an informative message as the timeout approaches. |
| @end multitable |
| |
| @item 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: |
| |
| @multitable @columnfractions 0.3 0.6 |
| @item id |
| @tab Set to ``__timeout__`` to display the time elapsed to an automatical |
| boot of the default entry. |
| @item center_bitmap |
| @tab The file name of the image to draw in the center of the component. |
| @item tick_bitmap |
| @tab The file name of the image to draw for the tick marks. |
| @item num_ticks |
| @tab The number of ticks that make up a full circle. |
| @item ticks_disappear |
| @tab Boolean value indicating whether tick marks should progressively appear, |
| or progressively disappear as *value* approaches *end*. Specify |
| ``true`` or ``false``. Default is ``false``. |
| @item start_angle |
| @tab The position of the first tick mark to appear or disappear. |
| Measured in "parrots", 1 "parrot" = 1 / 256 of the full circle. |
| Use values ``xxx deg`` or ``xxx \xc2\xb0`` to set the angle in degrees. |
| @end multitable |
| |
| @item boot_menu |
| Displays the GRUB boot menu. It allows selecting items and executing them. |
| |
| Properties: |
| |
| @multitable @columnfractions 0.4 0.5 |
| @item item_font |
| @tab The font to use for the menu item titles. |
| @item selected_item_font |
| @tab 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 item_color |
| @tab The color to use for the menu item titles. |
| @item selected_item_color |
| @tab The color to use for the selected menu item, or ``inherit`` (the default) |
| to use ``item_color`` for the selected menu item as well. |
| @item icon_width |
| @tab The width of menu item icons. Icons are scaled to the specified size. |
| @item icon_height |
| @tab The height of menu item icons. |
| @item item_height |
| @tab The height of each menu item in pixels. |
| @item item_padding |
| @tab The amount of space in pixels to leave on each side of the menu item |
| contents. |
| @item item_icon_space |
| @tab The space between an item's icon and the title text, in pixels. |
| @item item_spacing |
| @tab The amount of space to leave between menu items, in pixels. |
| @item menu_pixmap_style |
| @tab 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.) |
| @item item_pixmap_style |
| @tab The image file pattern for the item styled box. |
| @item selected_item_pixmap_style |
| @tab The image file pattern for the selected item highlight styled box. |
| @item scrollbar |
| @tab Boolean value indicating whether the scroll bar should be drawn if the |
| frame and thumb styled boxes are configured. |
| @item scrollbar_frame |
| @tab The image file pattern for the entire scroll bar. |
| Example: ``scrollbar_*.png`` |
| @item scrollbar_thumb |
| @tab The image file pattern for the scroll bar thumb (the part of the scroll |
| bar that moves as scrolling occurs). |
| Example: ``scrollbar_thumb_*.png`` |
| @item scrollbar_thumb_overlay |
| @tab If this option is set to ``true`` then the scrollbar thumb |
| side slices (every slice except the center slice) will overlay the |
| scrollbar frame side slices. And the center slice of the scrollbar_thumb |
| can move all the way (from top to bottom), being drawn on the center |
| slice of the scrollbar frame. That way we can make a scrollbar with |
| round-shaped edges so there won't be a free space from the thumb to |
| the frame in top and bottom scrollbar positions. Default is ``false``. |
| @item scrollbar_slice |
| @tab The menu frame styled box's slice in which the scrollbar will be |
| drawn. Possible values are ``west``, ``center``, ``east`` (default). |
| ``west`` - the scrollbar will be drawn in the west slice (right-aligned). |
| ``east`` - the scrollbar will be drawn in the east slice (left-aligned). |
| ``center`` - the scrollbar will be drawn in the center slice. |
| Note: in case of ``center`` slice: |
| a) If the scrollbar should be drawn then boot menu entry's width is |
| decreased by the scrollbar's width and the scrollbar is drawn at the |
| right side of the center slice. |
| b) If the scrollbar won't be drawn then the boot menu entry's width |
| is the width of the center slice. |
| c) We don't necessary need the menu pixmap box to display the scrollbar. |
| @item scrollbar_left_pad |
| @tab The left scrollbar padding in pixels. |
| Unused if ``scrollbar_slice`` is ``west``. |
| @item scrollbar_right_pad |
| @tab The right scrollbar padding in pixels. |
| Unused if ``scrollbar_slice`` is ``east``. |
| @item scrollbar_top_pad |
| @tab The top scrollbar padding in pixels. |
| @item scrollbar_bottom_pad |
| @tab The bottom scrollbar padding in pixels. |
| @item visible |
| @tab Set to ``false`` to hide the boot menu. |
| @end multitable |
| |
| @item 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. |
| |
| @item 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. |
| |
| @item 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. |
| @end itemize |
| |
| |
| @subsection Common properties |
| |
| The following properties are supported by all components: |
| @table @samp |
| @item left |
| The distance from the left border of container to left border of the object in either of three formats: |
| @multitable @columnfractions 0.2 0.7 |
| @item x @tab Value in pixels |
| @item p% @tab Percentage |
| @item p%+x @tab mixture of both |
| @end multitable |
| @item top |
| The distance from the left border of container to left border of the object in same format. |
| @item width |
| The width of object in same format. |
| @item height |
| The height of object in same format. |
| @item 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: |
| |
| @multitable @columnfractions 0.2 0.7 |
| @item ``__timeout__`` |
| @tab Component with this ID will be updated by GRUB and will indicate |
| time elapsed to an automatical boot of the default entry. |
| Affected components: ``label``, ``circular_progress``, ``progress_bar``. |
| @end multitable |
| @end table |
| |
| |
| |
| @node Network |
| @chapter Booting GRUB from the network |
| |
| The following instructions don't work for *-emu, i386-qemu, i386-coreboot, |
| i386-multiboot, mips_loongson, mips-arc and mips_qemu_mips |
| |
| To generate a netbootable directory, run: |
| |
| @example |
| @group |
| grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/<platform> |
| @end group |
| @end example |
| |
| E.g. for i386-pc: |
| |
| @example |
| @group |
| grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/i386-pc |
| @end group |
| @end example |
| |
| Then follow instructions printed out by grub-mknetdir on configuring your DHCP |
| server. |
| |
| After GRUB has started, files on the TFTP server will be accessible via the |
| @samp{(tftp)} device. |
| |
| The server IP address can be controlled by changing the |
| @samp{(tftp)} device name to @samp{(tftp,@var{server-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. In the following description |
| @var{<interface>} is placeholder for the name of network interface (platform |
| dependent): |
| |
| @table @samp |
| @item net_@var{<interface>}_ip |
| The network interface's IP address. Read-only. |
| |
| @item net_@var{<interface>}_mac |
| The network interface's MAC address. Read-only. |
| |
| @item net_@var{<interface>}_hostname |
| The client host name provided by DHCP. Read-only. |
| |
| @item net_@var{<interface>}_domain |
| The client domain name provided by DHCP. Read-only. |
| |
| @item net_@var{<interface>}_rootpath |
| The path to the client's root disk provided by DHCP. Read-only. |
| |
| @item net_@var{<interface>}_extensionspath |
| The path to additional DHCP vendor extensions provided by DHCP. Read-only. |
| |
| @item net_@var{<interface>}_boot_file |
| The boot file name provided by DHCP. Read-only. |
| |
| @item net_@var{<interface>}_dhcp_server_name |
| The name of the DHCP server responsible for these boot parameters. |
| Read-only. |
| |
| @item net_@var{<interface>}_next_server |
| The IP address of the next (usually, TFTP) server provided by DHCP. |
| Read-only. |
| |
| @item net_default_interface |
| Initially set to name of network interface that was used to load grub. |
| Read-write, although setting it affects only interpretation of |
| @samp{net_default_ip} and @samp{net_default_mac} |
| |
| @item net_default_ip |
| The IP address of default interface. Read-only. This is alias for the |
| @samp{net_$@{net_default_interface@}_ip}. |
| |
| @item net_default_mac |
| The default interface's MAC address. Read-only. This is alias for the |
| @samp{net_$@{net_default_interface@}_mac}. |
| |
| @item net_default_server |
| The default server used by network drives (@pxref{Device syntax}). Read-write, |
| although setting this is only useful before opening a network device. |
| |
| @end table |
| |
| |
| @node Serial terminal |
| @chapter 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: |
| |
| @example |
| @group |
| grub> @kbd{serial --unit=0 --speed=9600} |
| grub> @kbd{terminal_input serial; terminal_output serial} |
| @end group |
| @end example |
| |
| The command @command{serial} initializes the serial unit 0 with the |
| speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if |
| you want to use COM2, you must specify @samp{--unit=1} instead. This |
| command accepts many other options, so please refer to @ref{serial}, |
| for more details. |
| |
| The commands @command{terminal_input} (@pxref{terminal_input}) and |
| @command{terminal_output} (@pxref{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 @code{console} to the command, |
| as @samp{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 @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. |
| |
| |
| @node Vendor power-on keys |
| @chapter 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 @samp{GRUB_TIMEOUT_BUTTON}, |
| @samp{GRUB_TIMEOUT_STYLE_BUTTON}, @samp{GRUB_DEFAULT_BUTTON}, and |
| @samp{GRUB_BUTTON_CMOS_ADDRESS} variables in default/grub (@pxref{Simple |
| configuration}). @samp{GRUB_TIMEOUT_BUTTON}, |
| @samp{GRUB_TIMEOUT_STYLE_BUTTON}, and @samp{GRUB_DEFAULT_BUTTON} are used |
| instead of the corresponding variables without the @samp{_BUTTON} suffix |
| when powered on using the special button. @samp{GRUB_BUTTON_CMOS_ADDRESS} |
| is vendor-specific and partially model-specific. Values known to the GRUB |
| team are: |
| |
| @table @key |
| @item Dell XPS M1330M |
| 121:3 |
| @item Dell XPS M1530 |
| 85:3 |
| @item Dell Latitude E4300 |
| 85:3 |
| @item Asus EeePC 1005PE |
| 84:1 (unconfirmed) |
| @item LENOVO ThinkPad T410s (2912W1C) |
| 101:3 |
| @end table |
| |
| To take full advantage of this function, install GRUB into the MBR |
| (@pxref{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: |
| @itemize |
| @item boot normally |
| @item |
| @example |
| sudo modprobe nvram |
| sudo cat /dev/nvram | xxd > normal_button.txt |
| @end example |
| @item boot using vendor button |
| @item |
| @example |
| sudo modprobe nvram |
| sudo cat /dev/nvram | xxd > normal_vendor.txt |
| @end example |
| @end itemize |
| |
| Then compare these text files and find where a bit was toggled. E.g. in |
| case of Dell XPS it was: |
| @example |
| byte 0x47: 20 --> 28 |
| @end example |
| It's a bit number 3 as seen from following table: |
| @multitable @columnfractions .2 .2 |
| @item 0 @tab 01 |
| @item 1 @tab 02 |
| @item 2 @tab 04 |
| @item 3 @tab 08 |
| @item 4 @tab 10 |
| @item 5 @tab 20 |
| @item 6 @tab 40 |
| @item 7 @tab 80 |
| @end multitable |
| |
| 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 |
| |
| @node Images |
| @chapter GRUB image files |
| |
| @c FIXME: parts of this section are specific to PC BIOS right now. |
| |
| 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. |
| |
| @table @file |
| @item 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 @file{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, |
| @file{boot.img} cannot understand any file system structure, so |
| @command{grub-install} hardcodes the location of the first sector of the |
| core image into @file{boot.img} when installing GRUB. |
| |
| @item 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. |
| |
| @item 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 @file{diskboot.img}. |
| |
| @item pxeboot.img |
| This image is used as the start of the core image when booting from the |
| network using PXE. @xref{Network}. |
| |
| @item 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 |
| @samp{image=} section. |
| |
| @item 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. |
| |
| @item 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 @command{grub-mkimage} |
| program. Usually, it contains enough modules to access @file{/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. |
| |
| @xref{BIOS installation}, for details on where the core image can be |
| installed on PC systems. |
| |
| @item *.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 @command{insmod} |
| command (@pxref{insmod}). |
| @end table |
| |
| @heading 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. |
| |
| @table @file |
| @item stage1 |
| Stage 1 from GRUB Legacy was very similar to @file{boot.img} in GRUB 2, and |
| they serve the same function. |
| |
| @item *_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 @file{core.img} in GRUB 2. |
| However, @file{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. @file{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 @file{core.img} and cannot work |
| without it. |
| |
| @item stage2 |
| GRUB 2 has no single Stage 2 image. Instead, it loads modules from |
| @file{/boot/grub} at run-time. |
| |
| @item stage2_eltorito |
| In GRUB 2, images for booting from CD-ROM drives are now constructed using |
| @file{cdboot.img} and @file{core.img}, making sure that the core image |
| contains the @samp{iso9660} module. It is usually best to use the |
| @command{grub-mkrescue} program for this. |
| |
| @item nbgrub |
| There is as yet no equivalent for @file{nbgrub} in GRUB 2; it was used by |
| Etherboot and some other network boot loaders. |
| |
| @item pxegrub |
| In GRUB 2, images for PXE network booting are now constructed using |
| @file{pxeboot.img} and @file{core.img}, making sure that the core image |
| contains the @samp{pxe} and @samp{pxecmd} modules. @xref{Network}. |
| @end table |
| |
| @node Core image size limitation |
| @chapter Core image size limitation |
| |
| Heavily limited platforms: |
| @itemize |
| @item i386-pc (normal and PXE): the core image size (compressed) is limited by 458240 bytes. |
| kernel.img (.text + .data + .bss, uncompressed) is limited by 392704 bytes. |
| module size (uncompressed) + kernel.img (.text + .data, uncompressed) is limited by the size of contiguous chunk at 1M address. |
| @item sparc64-ieee1275: kernel.img (.text + .data + .bss) + modules + 256K (stack) + 2M (heap) is limited by space available at 0x4400. On most platforms it's just 3 or 4M since ieee1275 maps only so much. |
| @item i386-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by memory available at 0x10000, at most 596K |
| @end itemize |
| |
| Lightly limited platforms: |
| |
| @itemize |
| @item *-xen: limited only by adress space and RAM size. |
| @item i386-qemu: kernel.img (.text + .data + .bss) is limited by 392704 bytes. |
| (core.img would be limited by ROM size but it's unlimited on qemu |
| @item All EFI platforms: limited by contiguous RAM size and possibly firmware bugs |
| @item Coreboot and multiboot. kernel.img (.text + .data + .bss) is limited by 392704 bytes. |
| module size is limited by the size of contiguous chunk at 1M address. |
| @item mipsel-loongson (ELF), mips(el)-qemu_mips (ELF): if uncompressed: |
| kernel.img (.text + .data) + modules is limited by the space from 80200000 forward |
| if compressed: |
| kernel.img (.text + .data, uncompressed) + modules (uncompressed) |
| + (modules + kernel.img (.text + .data)) (compressed) |
| + decompressor is limited by the space from 80200000 forward |
| @item mipsel-loongson (Flash), mips(el)-qemu_mips (Flash): kernel.img (.text + .data) + modules is limited by the space from 80200000 forward |
| core.img (final) is limited by flash size (512K on yeeloong and fulooong) |
| @item mips-arc: if uncompressed: |
| kernel.img (.text + .data) is limited by the space from 8bd00000 forward |
| modules + dummy decompressor is limited by the space from 8bd00000 backward |
| if compressed: |
| kernel.img (.text + .data, uncompressed) is limited by the space from 8bd00000 forward |
| modules (uncompressed) + (modules + kernel.img (.text + .data)) (compressed, aligned to 1M) |
| + 1M (decompressor + scratch space) is limited by the space from 8bd00000 backward |
| @item powerpc-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by space available at 0x200000 |
| @end itemize |
| |
| @node Filesystem |
| @chapter 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 @command{search} |
| (@pxref{search}). |
| |
| @menu |
| * Device syntax:: How to specify devices |
| * File name syntax:: How to specify files |
| * Block list syntax:: How to specify block lists |
| @end menu |
| |
| |
| @node Device syntax |
| @section How to specify devices |
| |
| The device syntax is like this: |
| |
| @example |
| @code{(@var{device}[,@var{partmap-name1}@var{part-num1}[,@var{partmap-name2}@var{part-num2}[,...]]])} |
| @end example |
| |
| @samp{[]} means the parameter is optional. @var{device} depends on the disk |
| driver in use. BIOS and EFI disks use either @samp{fd} or @samp{hd} followed |
| by a digit, like @samp{fd0}, or @samp{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 (lvm), LDM, virtio (vdsk) |
| 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 @command{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>. For LVM additionally you can use the syntax |
| lvmid/<volume-group-uuid>/<volume-uuid>. |
| |
| @example |
| (fd0) |
| (hd0) |
| (cd) |
| (ahci0) |
| (ata0) |
| (crypto0) |
| (usb0) |
| (cryptouuid/123456789abcdef0123456789abcdef0) |
| (mduuid/123456789abcdef0123456789abcdef0) |
| (lvm/system-root) |
| (lvmid/F1ikgD-2RES-306G-il9M-7iwa-4NKW-EbV1NV/eLGuCQ-L4Ka-XUgR-sjtJ-ffch-bajr-fCNfz5) |
| (md/myraid) |
| (md/0) |
| (ieee1275/disk2) |
| (ieee1275//pci@@1f\,0/ide@@d/disk@@2) |
| (nand) |
| (memdisk) |
| (host) |
| (myloop) |
| (hostdisk//dev/sda) |
| @end example |
| |
| @var{part-num} represents the partition number of @var{device}, starting |
| from one. @var{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 @samp{(hd0)} represents using the entire disk (or the |
| MBR when installing GRUB), while the syntax @samp{(hd0,1)} |
| represents using the first partition of the disk (or the boot sector |
| of the partition when installing GRUB). |
| |
| @example |
| (hd0,msdos1) |
| (hd0,msdos1,msdos5) |
| (hd0,msdos1,bsd3) |
| (hd0,netbsd1) |
| (hd0,gpt1) |
| (hd0,1,3) |
| @end example |
| |
| If you enabled the network support, the special drives |
| @code{(@var{protocol}[,@var{server}])} are also available. Supported protocols |
| are @samp{http} and @samp{tftp}. If @var{server} is omitted, value of |
| environment variable @samp{net_default_server} is used. |
| Before using the network drive, you must initialize the network. |
| @xref{Network}, for more information. |
| |
| If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making |
| a GRUB bootable CD-ROM}, for details. |
| |
| |
| @node File name syntax |
| @section How to specify files |
| |
| There are two ways to specify files, by @dfn{absolute file name} and by |
| @dfn{block list}. |
| |
| An absolute file name resembles a Unix absolute file name, using |
| @samp{/} for the directory separator (not @samp{\} as in DOS). One |
| example is @samp{(hd0,1)/boot/grub/grub.cfg}. This means the file |
| @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 @dfn{root device} implicitly. So if you set the root device to, |
| say, @samp{(hd1,1)} by the command @samp{set root=(hd1,1)} (@pxref{set}), |
| then @code{/boot/kernel} is the same as @code{(hd1,1)/boot/kernel}. |
| |
| On ZFS filesystem the first path component must be |
| @var{volume}@samp{@@}[@var{snapshot}]. |
| So @samp{/rootvol@@snap-129/boot/grub/grub.cfg} refers to file |
| @samp{/boot/grub/grub.cfg} in snapshot of volume @samp{rootvol} with name |
| @samp{snap-129}. Trailing @samp{@@} after volume name is mandatory even if |
| snapshot name is omitted. |
| |
| |
| @node Block list syntax |
| @section 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 |
| @code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. |
| Here is an example: |
| |
| @example |
| @code{0+100,200+1,300+300} |
| @end example |
| |
| 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 (@pxref{File name syntax}), if a blocklist |
| does not contain a device name, then GRUB uses GRUB's @dfn{root |
| device}. So @code{(hd0,2)+1} is the same as @code{+1} when the root |
| device is @samp{(hd0,2)}. |
| |
| |
| @node Interface |
| @chapter 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 @dfn{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 |
| @end menu |
| |
| |
| @node Command-line interface |
| @section 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@footnote{However, this |
| behavior will be changed in the future version, in a user-invisible |
| way.}. The commands (@pxref{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: |
| |
| @table @key |
| @item C-f |
| @itemx PC right key |
| Move forward one character. |
| |
| @item C-b |
| @itemx PC left key |
| Move back one character. |
| |
| @item C-a |
| @itemx HOME |
| Move to the start of the line. |
| |
| @item C-e |
| @itemx END |
| Move the the end of the line. |
| |
| @item C-d |
| @itemx DEL |
| Delete the character underneath the cursor. |
| |
| @item C-h |
| @itemx BS |
| Delete the character to the left of the cursor. |
| |
| @item C-k |
| Kill the text from the current cursor position to the end of the line. |
| |
| @item C-u |
| Kill backward from the cursor to the beginning of the line. |
| |
| @item C-y |
| Yank the killed text back into the buffer at the cursor. |
| |
| @item C-p |
| @itemx PC up key |
| Move up through the history list. |
| |
| @item C-n |
| @itemx PC down key |
| Move down through the history list. |
| @end table |
| |
| When typing commands interactively, if the cursor is within or before |
| the first word in the command-line, pressing the @key{TAB} key (or |
| @key{C-i}) will display a listing of the available commands, and if the |
| cursor is after the first word, the @kbd{@key{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 @command{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. |
| |
| |
| @node Menu interface |
| @section 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 @dfn{boot entries} to |
| the user to choose from. Use the arrow keys to select the entry of |
| choice, then press @key{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 @key{c} |
| (which operates exactly like the non-config-file version of GRUB, but |
| allows one to return to the menu if desired by pressing @key{ESC}) or to |
| edit any of the @dfn{boot entries} by pressing @key{e}. |
| |
| If you protect the menu interface with a password (@pxref{Security}), |
| all you can do is choose an entry by pressing @key{RET}, or press |
| @key{p} to enter the password. |
| |
| |
| @node Menu entry editor |
| @section 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 @key{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 @key{RET} at the end of a line. To boot the edited entry, press |
| @key{Ctrl-x}. |
| |
| Although GRUB unfortunately does not support @dfn{undo}, you can do almost |
| the same thing by just returning to the main menu using @key{ESC}. |
| |
| |
| @node Environment |
| @chapter 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 (@pxref{set}), unset (@pxref{unset}), or |
| looked up (@pxref{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:: |
| @end menu |
| |
| |
| @node Special environment variables |
| @section Special environment variables |
| |
| These variables have special meaning to GRUB. |
| |
| @menu |
| * biosnum:: |
| * check_signatures:: |
| * chosen:: |
| * cmdpath:: |
| * color_highlight:: |
| * color_normal:: |
| * config_directory:: |
| * config_file:: |
| * debug:: |
| * default:: |
| * fallback:: |
| * gfxmode:: |
| * gfxpayload:: |
| * gfxterm_font:: |
| * grub_cpu:: |
| * grub_platform:: |
| * icondir:: |
| * lang:: |
| * locale_dir:: |
| * menu_color_highlight:: |
| * menu_color_normal:: |
| * net_@var{<interface>}_boot_file:: |
| * net_@var{<interface>}_dhcp_server_name:: |
| * net_@var{<interface>}_domain:: |
| * net_@var{<interface>}_extensionspath:: |
| * net_@var{<interface>}_hostname:: |
| * net_@var{<interface>}_ip:: |
| * net_@var{<interface>}_mac:: |
| * net_@var{<interface>}_next_server:: |
| * net_@var{<interface>}_rootpath:: |
| * net_default_interface:: |
| * net_default_ip:: |
| * net_default_mac:: |
| * net_default_server:: |
| * pager:: |
| * prefix:: |
| * pxe_blksize:: |
| * pxe_default_gateway:: |
| * pxe_default_server:: |
| * root:: |
| * superusers:: |
| * theme:: |
| * timeout:: |
| * timeout_style:: |
| @end menu |
| |
| |
| @node biosnum |
| @subsection biosnum |
| |
| When chain-loading another boot loader (@pxref{Chain-loading}), GRUB may |
| need to know what BIOS drive number corresponds to the root device |
| (@pxref{root}) so that it can set up registers properly. If the |
| @var{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, @pxref{drivemap}. |
| |
| |
| @node check_signatures |
| @subsection check_signatures |
| |
| This variable controls whether GRUB enforces digital signature |
| validation on loaded files. @xref{Using digital signatures}. |
| |
| @node chosen |
| @subsection chosen |
| |
| When executing a menu entry, GRUB sets the @var{chosen} variable to the |
| title of the entry being executed. |
| |
| If the menu entry is in one or more submenus, then @var{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 @samp{>}. |
| |
| |
| @node cmdpath |
| @subsection cmdpath |
| |
| The location from which @file{core.img} was loaded as an absolute |
| directory name (@pxref{File name syntax}). This is set by GRUB at |
| startup based on information returned by platform firmware. Not every |
| platform provides this information and some may return only device |
| without path name. |
| |
| |
| @node color_highlight |
| @subsection color_highlight |
| |
| This variable contains the ``highlight'' foreground and background terminal |
| colors, separated by a slash (@samp{/}). Setting this variable changes |
| those colors. For the available color names, @pxref{color_normal}. |
| |
| The default is @samp{black/light-gray}. |
| |
| |
| @node color_normal |
| @subsection color_normal |
| |
| This variable contains the ``normal'' foreground and background terminal |
| colors, separated by a slash (@samp{/}). Setting this variable changes |
| those colors. Each color must be a name from the following list: |
| |
| @itemize @bullet |
| @item black |
| @item blue |
| @item green |
| @item cyan |
| @item red |
| @item magenta |
| @item brown |
| @item light-gray |
| @item dark-gray |
| @item light-blue |
| @item light-green |
| @item light-cyan |
| @item light-red |
| @item light-magenta |
| @item yellow |
| @item white |
| @end itemize |
| |
| The default is @samp{light-gray/black}. |
| |
| The color support support varies from terminal to terminal. |
| |
| @samp{morse} has no color support at all. |
| |
| @samp{mda_text} color support is limited to highlighting by |
| black/white reversal. |
| |
| @samp{console} on ARC, EMU and IEEE1275, @samp{serial_*} and |
| @samp{spkmodem} are governed by terminfo and support |
| only 8 colors if in modes @samp{vt100-color} (default for console on emu), |
| @samp{arc} (default for console on ARC), @samp{ieee1275} (default |
| for console on IEEE1275). When in mode @samp{vt100} |
| then the color support is limited to highlighting by black/white |
| reversal. When in mode @samp{dumb} there is no color support. |
| |
| When console supports no colors this setting is ignored. |
| When console supports 8 colors, then the colors from the |
| second half of the previous list are mapped to the |
| matching colors of first half. |
| |
| @samp{console} on EFI and BIOS and @samp{vga_text} support all 16 colors. |
| |
| @samp{gfxterm} supports all 16 colors and would be theoretically extendable |
| to support whole rgb24 palette but currently there is no compelling reason |
| to go beyond the current 16 colors. |
| |
| |
| @node config_directory |
| @subsection config_directory |
| |
| This variable is automatically set by GRUB to the directory part of |
| current configuration file name (@pxref{config_file}). |
| |
| |
| @node config_file |
| @subsection config_file |
| |
| This variable is automatically set by GRUB to the name of configuration file that is being |
| processed by commands @command{configfile} (@pxref{configfile}) or @command{normal} |
| (@pxref{normal}). It is restored to the previous value when command completes. |
| |
| |
| @node debug |
| @subsection 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 @samp{,}, or @samp{all} to enable all available debugging |
| output. The facility names are the first argument to grub_dprintf. Consult |
| source for more details. |
| |
| |
| @node default |
| @subsection default |
| |
| If this variable is set, it identifies a menu entry that should be |
| selected by default, possibly after a timeout (@pxref{timeout}). The |
| entry may be identified by number (starting from 0 at each level of |
| the hierarchy), by title, or by id. |
| |
| For example, if you have: |
| |
| @verbatim |
| menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux { |
| ... |
| } |
| @end verbatim |
| |
| then you can make this the default using: |
| |
| @example |
| default=example-gnu-linux |
| @end example |
| |
| If the entry is in a submenu, then it must be identified using the |
| number, title, or id of each of the submenus starting from the top |
| level, followed by the number, title, or id of the menu entry itself, |
| with each element separated by @samp{>}. For example, take the |
| following menu structure: |
| |
| @example |
| GNU/Hurd --id gnu-hurd |
| Standard Boot --id=gnu-hurd-std |
| Rescue shell --id=gnu-hurd-rescue |
| Other platforms --id=other |
| Minix --id=minix |
| Version 3.4.0 --id=minix-3.4.0 |
| Version 3.3.0 --id=minix-3.3.0 |
| GRUB Invaders --id=grub-invaders |
| @end example |
| |
| The more recent release of Minix would then be identified as |
| @samp{Other platforms>Minix>Version 3.4.0}, or as @samp{1>0>0}, or as |
| @samp{other>minix>minix-3.4.0}. |
| |
| This variable is often set by @samp{GRUB_DEFAULT} (@pxref{Simple |
| configuration}), @command{grub-set-default}, or @command{grub-reboot}. |
| |
| |
| @node fallback |
| @subsection 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 @samp{default} (@pxref{default}). |
| |
| |
| @node gfxmode |
| @subsection gfxmode |
| |
| If this variable is set, it sets the resolution used on the @samp{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 @samp{auto}, which |
| selects a platform-specific default that should look reasonable. Supported |
| modes can be listed by @samp{videoinfo} command in GRUB. |
| |
| The resolution may be specified as a sequence of one or more modes, |
| separated by commas (@samp{,}) or semicolons (@samp{;}); each will be tried |
| in turn until one is found. Each mode should be either @samp{auto}, |
| @samp{@var{width}x@var{height}}, or |
| @samp{@var{width}x@var{height}x@var{depth}}. |
| |
| |
| @node gfxpayload |
| @subsection gfxpayload |
| |
| If this variable is set, it controls the video mode in which the Linux |
| kernel starts up, replacing the @samp{vga=} boot option (@pxref{linux}). It |
| may be set to @samp{text} to force the Linux kernel to boot in normal text |
| mode, @samp{keep} to preserve the graphics mode set using @samp{gfxmode}, or |
| any of the permitted values for @samp{gfxmode} to set a particular graphics |
| mode (@pxref{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 @samp{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 @samp{text}. Otherwise the |
| default may be @samp{auto} or a specific video mode. |
| |
| This variable is often set by @samp{GRUB_GFXPAYLOAD_LINUX} (@pxref{Simple |
| configuration}). |
| |
| |
| @node gfxterm_font |
| @subsection gfxterm_font |
| |
| If this variable is set, it names a font to use for text on the |
| @samp{gfxterm} graphical terminal. Otherwise, @samp{gfxterm} may use any |
| available font. |
| |
| |
| @node grub_cpu |
| @subsection grub_cpu |
| |
| In normal mode (@pxref{normal}), GRUB sets the @samp{grub_cpu} variable to |
| the CPU type for which GRUB was built (e.g. @samp{i386} or @samp{powerpc}). |
| |
| |
| @node grub_platform |
| @subsection grub_platform |
| |
| In normal mode (@pxref{normal}), GRUB sets the @samp{grub_platform} variable |
| to the platform for which GRUB was built (e.g. @samp{pc} or @samp{efi}). |
| |
| |
| @node icondir |
| @subsection 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 @samp{icons} |
| directory. @xref{Theme file format}. |
| |
| |
| @node lang |
| @subsection lang |
| |
| If this variable is set, it names the language code that the |
| @command{gettext} command (@pxref{gettext}) uses to translate strings. For |
| example, French would be named as @samp{fr}, and Simplified Chinese as |
| @samp{zh_CN}. |
| |
| @command{grub-mkconfig} (@pxref{Simple configuration}) will try to set a |
| reasonable default for this variable based on the system locale. |
| |
| |
| @node locale_dir |
| @subsection locale_dir |
| |
| If this variable is set, it names the directory where translation files may |
| be found (@pxref{gettext}), usually @file{/boot/grub/locale}. Otherwise, |
| internationalization is disabled. |
| |
| @command{grub-mkconfig} (@pxref{Simple configuration}) will set a reasonable |
| default for this variable if internationalization is needed and any |
| translation files are available. |
| |
| |
| @node menu_color_highlight |
| @subsection menu_color_highlight |
| |
| This variable contains the foreground and background colors to be used for |
| the highlighted menu entry, separated by a slash (@samp{/}). Setting this |
| variable changes those colors. For the available color names, |
| @pxref{color_normal}. |
| |
| The default is the value of @samp{color_highlight} |
| (@pxref{color_highlight}). |
| |
| |
| @node menu_color_normal |
| @subsection menu_color_normal |
| |
| This variable contains the foreground and background colors to be used for |
| non-highlighted menu entries, separated by a slash (@samp{/}). Setting this |
| variable changes those colors. For the available color names, |
| @pxref{color_normal}. |
| |
| The default is the value of @samp{color_normal} (@pxref{color_normal}). |
| |
| |
| @node net_@var{<interface>}_boot_file |
| @subsection net_@var{<interface>}_boot_file |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_dhcp_server_name |
| @subsection net_@var{<interface>}_dhcp_server_name |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_domain |
| @subsection net_@var{<interface>}_domain |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_extensionspath |
| @subsection net_@var{<interface>}_extensionspath |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_hostname |
| @subsection net_@var{<interface>}_hostname |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_ip |
| @subsection net_@var{<interface>}_ip |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_mac |
| @subsection net_@var{<interface>}_mac |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_next_server |
| @subsection net_@var{<interface>}_next_server |
| |
| @xref{Network}. |
| |
| |
| @node net_@var{<interface>}_rootpath |
| @subsection net_@var{<interface>}_rootpath |
| |
| @xref{Network}. |
| |
| |
| @node net_default_interface |
| @subsection net_default_interface |
| |
| @xref{Network}. |
| |
| |
| @node net_default_ip |
| @subsection net_default_ip |
| |
| @xref{Network}. |
| |
| |
| @node net_default_mac |
| @subsection net_default_mac |
| |
| @xref{Network}. |
| |
| |
| @node net_default_server |
| @subsection net_default_server |
| |
| @xref{Network}. |
| |
| |
| @node pager |
| @subsection pager |
| |
| If set to @samp{1}, pause output after each screenful and wait for keyboard |
| input. The default is not to pause output. |
| |
| |
| @node prefix |
| @subsection prefix |
| |
| The location of the @samp{/boot/grub} directory as an absolute file name |
| (@pxref{File name syntax}). This is normally set by GRUB at startup based |
| on information provided by @command{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. |
| |
| |
| @node pxe_blksize |
| @subsection pxe_blksize |
| |
| @xref{Network}. |
| |
| |
| @node pxe_default_gateway |
| @subsection pxe_default_gateway |
| |
| @xref{Network}. |
| |
| |
| @node pxe_default_server |
| @subsection pxe_default_server |
| |
| @xref{Network}. |
| |
| |
| @node root |
| @subsection root |
| |
| The root device name (@pxref{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 @samp{prefix} |
| (@pxref{prefix}). |
| |
| For example, if GRUB was installed to the first partition of the first hard |
| disk, then @samp{prefix} might be set to @samp{(hd0,msdos1)/boot/grub} and |
| @samp{root} to @samp{hd0,msdos1}. |
| |
| |
| @node superusers |
| @subsection superusers |
| |
| This variable may be set to a list of superuser names to enable |
| authentication support. @xref{Security}. |
| |
| |
| @node theme |
| @subsection theme |
| |
| This variable may be set to a directory containing a GRUB graphical menu |
| theme. @xref{Theme file format}. |
| |
| This variable is often set by @samp{GRUB_THEME} (@pxref{Simple |
| configuration}). |
| |
| |
| @node timeout |
| @subsection 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 @samp{0} |
| means to boot the default entry immediately without displaying the menu; a |
| timeout of @samp{-1} (or unset) means to wait indefinitely. |
| |
| If @samp{timeout_style} (@pxref{timeout_style}) is set to @samp{countdown} |
| or @samp{hidden}, the timeout is instead counted before the menu is |
| displayed. |
| |
| This variable is often set by @samp{GRUB_TIMEOUT} (@pxref{Simple |
| configuration}). |
| |
| |
| @node timeout_style |
| @subsection timeout_style |
| |
| This variable may be set to @samp{menu}, @samp{countdown}, or @samp{hidden} |
| to control the way in which the timeout (@pxref{timeout}) interacts with |
| displaying the menu. See the documentation of @samp{GRUB_TIMEOUT_STYLE} |
| (@pxref{Simple configuration}) for details. |
| |
| |
| @node Environment block |
| @section 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 @file{/boot/grub/grubenv} (although you should not assume this). At boot |
| time, the @command{load_env} command (@pxref{load_env}) loads environment |
| variables from it, and the @command{save_env} (@pxref{save_env}) command |
| saves environment variables to it. From a running system, the |
| @command{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). |
| |
| @command{grub-mkconfig} uses this facility to implement |
| @samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}). |
| |
| |
| @node Commands |
| @chapter 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 @command{insmod} (@pxref{insmod}), @command{ls} |
| (@pxref{ls}), @command{set} (@pxref{set}), and @command{unset} |
| (@pxref{unset}) commands are normally available. If you end up in rescue |
| mode and do not know what to do, then @pxref{GRUB only offers a rescue |
| shell}. |
| |
| @menu |
| * Menu-specific commands:: |
| * General commands:: |
| * Command-line and menu entry commands:: |
| * Networking commands:: |
| @end menu |
| |
| |
| @node Menu-specific commands |
| @section The list of commands for the menu only |
| |
| The semantics used in parsing the configuration file are the following: |
| |
| @itemize @bullet |
| @item |
| The files @emph{must} be in plain-text format. |
| |
| @item |
| @samp{#} at the beginning of a line in a configuration file means it is |
| only a comment. |
| |
| @item |
| Options are separated by spaces. |
| |
| @item |
| All numbers can be either decimal or hexadecimal. A hexadecimal number |
| must be preceded by @samp{0x}, and is case-insensitive. |
| @end itemize |
| |
| These commands can only be used in the menu: |
| |
| @menu |
| * menuentry:: Start a menu entry |
| * submenu:: Group menu entries |
| @end menu |
| |
| |
| @node menuentry |
| @subsection menuentry |
| |
| @deffn Command menuentry @var{title} @ |
| [@option{--class=class} @dots{}] [@option{--users=users}] @ |
| [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @ |
| [@var{arg} @dots{}] @{ @var{command}; @dots{} @} |
| This defines a GRUB menu entry named @var{title}. When this entry is |
| selected from the menu, GRUB will set the @var{chosen} environment variable |
| to value of @option{--id} if @option{--id} is given, 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 @command{boot} command. |
| |
| The @option{--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 @option{--users} option grants specific users access to specific menu |
| entries. @xref{Security}. |
| |
| The @option{--unrestricted} option grants all users access to specific menu |
| entries. @xref{Security}. |
| |
| The @option{--hotkey} option associates a hotkey with a menu entry. |
| @var{key} may be a single letter, or one of the aliases @samp{backspace}, |
| @samp{tab}, or @samp{delete}. |
| |
| The @option{--id} may be used to associate unique identifier with a menu entry. |
| @var{id} is string of ASCII aphanumeric characters, underscore and hyphen |
| and should not start with a digit. |
| |
| All other arguments including @var{title} are passed as positional parameters |
| when list of commands is executed with @var{title} always assigned to @code{$1}. |
| @end deffn |
| |
| |
| @node submenu |
| @subsection submenu |
| |
| @deffn Command submenu @var{title} @ |
| [@option{--class=class} @dots{}] [@option{--users=users}] @ |
| [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @ |
| @{ @var{menu entries} @dots{} @} |
| This defines a submenu. An entry called @var{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 @command{menuentry} command |
| (@pxref{menuentry}). |
| @end deffn |
| |
| |
| @node General commands |
| @section 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 |
| @end menu |
| |
| |
| @node serial |
| @subsection serial |
| |
| @deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] |
| Initialize a serial device. @var{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. @var{port} is the I/O port where the UART |
| is to be found; if specified it takes precedence over @var{unit}. |
| @var{speed} is the transmission speed; default is 9600. @var{word} and |
| @var{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. @var{parity} is one of @samp{no}, @samp{odd}, |
| @samp{even} and defaults to @samp{no}. |
| |
| The serial port is not used as a communication channel unless the |
| @command{terminal_input} or @command{terminal_output} command is used |
| (@pxref{terminal_input}, @pxref{terminal_output}). |
| |
| See also @ref{Serial terminal}. |
| @end deffn |
| |
| |
| @node terminal_input |
| @subsection terminal_input |
| |
| @deffn Command terminal_input [@option{--append}|@option{--remove}] @ |
| [terminal1] [terminal2] @dots{} |
| List or select an input terminal. |
| |
| With no arguments, list the active and available input terminals. |
| |
| With @option{--append}, add the named terminals to the list of active input |
| terminals; any of these may be used to provide input to GRUB. |
| |
| With @option{--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. |
| @end deffn |
| |
| |
| @node terminal_output |
| @subsection terminal_output |
| |
| @deffn Command terminal_output [@option{--append}|@option{--remove}] @ |
| [terminal1] [terminal2] @dots{} |
| List or select an output terminal. |
| |
| With no arguments, list the active and available output terminals. |
| |
| With @option{--append}, add the named terminals to the list of active output |
| terminals; all of these will receive output from GRUB. |
| |
| With @option{--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. |
| @end deffn |
| |
| |
| @node terminfo |
| @subsection terminfo |
| |
| @deffn 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 @samp{TERM} |
| environment variable in Unix. |
| |
| The currently available terminal types are @samp{vt100}, @samp{vt100-color}, |
| @samp{ieee1275}, and @samp{dumb}. If you need other terminal types, please |
| contact us to discuss the best way to include support for these in GRUB. |
| |
| The @option{-a} (@option{--ascii}), @option{-u} (@option{--utf8}), and |
| @option{-v} (@option{--visual-utf8}) options control how non-ASCII text is |
| displayed. @option{-a} specifies an ASCII-only terminal; @option{-u} |
| specifies logically-ordered UTF-8; and @option{-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. |
| @end deffn |
| |
| |
| @node Command-line and menu entry commands |
| @section 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 @command{help} |
| (@pxref{help}). |
| |
| @menu |
| * [:: Check file types and compare values |
| * acpi:: Load ACPI tables |
| * authenticate:: Check whether user is in user list |
| * background_color:: Set background color for active terminal |
| * background_image:: Load background image for active terminal |
| * 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 |
| * clear:: Clear the screen |
| * cmosclean:: Clear bit in CMOS |
| * cmosdump:: Dump CMOS contents |
| * cmostest:: Test bit in CMOS |
| * cmp:: Compare two files |
| * configfile:: Load a configuration file |
| * cpuid:: Check for CPU features |
| * crc:: Compute or check CRC32 checksums |
| * cryptomount:: Mount a crypto device |
| * date:: Display or set current date and time |
| * devicetree:: Load a device tree blob |
| * distrust:: Remove a pubkey from trusted keys |
| * drivemap:: Map a drive to another |
| * echo:: Display a line of text |
| * eval:: Evaluate agruments as GRUB commands |
| * 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 |
| * hashsum:: Compute or check hash checksum |
| * 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 |
| * list_trusted:: List trusted public keys |
| * load_env:: Load variables from environment block |
| * loadfont:: Load font files |
| * loopback:: Make a device from a filesystem image |
| * ls:: List devices or files |
| * lsfonts:: List loaded fonts |
| * lsmod:: Show loaded modules |
| * md5sum:: Compute or check MD5 hash |
| * module:: Load module for multiboot kernel |
| * multiboot:: Load multiboot compliant kernel |
| * nativedisk:: Switch to native disk drivers |
| * 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 |
| * probe:: Retrieve device info |
| * pxe_unload:: Unload the PXE environment |
| * read:: Read user input |
| * reboot:: Reboot your computer |
| * regexp:: Test if regular expression matches string |
| * rmmod:: Remove a module |
| * save_env:: Save variables to environment block |
| * search:: Search devices by file, label, or UUID |
| * sendkey:: Emulate keystrokes |
| * set:: Set an environment variable |
| * sha1sum:: Compute or check SHA1 hash |
| * sha256sum:: Compute or check SHA256 hash |
| * sha512sum:: Compute or check SHA512 hash |
| * sleep:: Wait for a specified number of seconds |
| * source:: Read a configuration file in same context |
| * test:: Check file types and compare values |
| * true:: Do nothing, successfully |
| * trust:: Add public key to list of trusted keys |
| * unset:: Unset an environment variable |
| * uppermem:: Set the upper memory size |
| @comment * vbeinfo:: List available video modes |
| * verify_detached:: Verify detached digital signature |
| * videoinfo:: List available video modes |
| @comment * xen_*:: Xen boot commands for AArch64 |
| * xen_hypervisor:: Load xen hypervisor binary (only on AArch64) |
| * xen_module:: Load xen modules for xen hypervisor (only on AArch64) |
| @end menu |
| |
| |
| @node [ |
| @subsection [ |
| @deffn Command @code{[} expression @code{]} |
| Alias for @code{test @var{expression}} (@pxref{test}). |
| @end deffn |
| |
| |
| @node acpi |
| @subsection acpi |
| |
| @deffn Command acpi [@option{-1}|@option{-2}] @ |
| [@option{--exclude=table1,@dots{}}|@option{--load-only=table1,@dots{}}] @ |
| [@option{--oemid=id}] [@option{--oemtable=table}] @ |
| [@option{--oemtablerev=rev}] [@option{--oemtablecreator=creator}] @ |
| [@option{--oemtablecreatorrev=rev}] [@option{--no-ebda}] @ |
| filename @dots{} |
| 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 |
| @option{--no-ebda} option is used, the new tables will be known only to |
| GRUB, but may be used by GRUB's EFI emulation. |
| @end deffn |
| |
| |
| @node authenticate |
| @subsection authenticate |
| @deffn Command authenticate [userlist] |
| Check whether user is in @var{userlist} or listed in the value of variable |
| @samp{superusers}. See @pxref{superusers} for valid user list format. |
| If @samp{superusers} is empty, this command returns true. @xref{Security}. |
| @end deffn |
| |
| |
| @node background_color |
| @subsection background_color |
| |
| @deffn Command background_color color |
| Set background color for active terminal. For valid color specifications see |
| @pxref{Theme file format, ,Colors}. Background color can be changed only when |
| using @samp{gfxterm} for terminal output. |
| |
| This command sets color of empty areas without text. Text background color |
| is controlled by environment variables @var{color_normal}, @var{color_highlight}, |
| @var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}. |
| @end deffn |
| |
| |
| @node background_image |
| @subsection background_image |
| |
| @deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file] |
| Load background image for active terminal from @var{file}. Image is stretched |
| to fill up entire screen unless option @option{--mode} @samp{normal} is given. |
| Without arguments remove currently loaded background image. Background image |
| can be changed only when using @samp{gfxterm} for terminal output. |
| |
| @end deffn |
| |
| |
| @node badram |
| @subsection badram |
| |
| @deffn Command badram addr,mask[,addr,mask...] |
| Filter out bad RAM. |
| @end deffn |
| |
| 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 @uref{http://www.memtest.org/, |
| Memtest86+ utility}: a list of address/mask pairs. Given a page-aligned |
| address and a base address / mask pair, if all the bits of the page-aligned |
| address that are enabled by the mask match with the base address, it means |
| this page is to be filtered. This syntax makes it easy to represent patterns |
| that are often result of memory damage, due to physical distribution of memory |
| cells. |
| |
| @node blocklist |
| @subsection blocklist |
| |
| @deffn Command blocklist file |
| Print a block list (@pxref{Block list syntax}) for @var{file}. |
| @end deffn |
| |
| |
| @node boot |
| @subsection boot |
| |
| @deffn 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). |
| @end deffn |
| |
| |
| @node cat |
| @subsection cat |
| |
| @deffn Command cat [@option{--dos}] file |
| Display the contents of the file @var{file}. This command may be useful |
| to remind you of your OS's root partition: |
| |
| @example |
| grub> @kbd{cat /etc/fstab} |
| @end example |
| |
| If the @option{--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 (@samp{<d>}) to make it easier to see |
| when boot problems are caused by a file formatted using DOS-style line |
| endings. |
| @end deffn |
| |
| |
| @node chainloader |
| @subsection chainloader |
| |
| @deffn Command chainloader [@option{--force}] file |
| Load @var{file} as a chain-loader. Like any other file loaded by the |
| filesystem code, it can use the blocklist notation (@pxref{Block list |
| syntax}) to grab the first sector of the current partition with @samp{+1}. |
| If you specify the option @option{--force}, then load @var{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. |
| @end deffn |
| |
| |
| @node clear |
| @subsection clear |
| |
| @deffn Command clear |
| Clear the screen. |
| @end deffn |
| |
| |
| @node cmosclean |
| @subsection cmosclean |
| |
| @deffn Command cmosclean byte:bit |
| Clear value of bit in CMOS at location @var{byte}:@var{bit}. This command |
| is available only on platforms that support CMOS. |
| @end deffn |
| |
| |
| @node cmosdump |
| @subsection cmosdump |
| |
| @deffn Dump CMOS contents |
| Dump full CMOS contents as hexadecimal values. This command is available only |
| on platforms that support CMOS. |
| @end deffn |
| |
| |
| @node cmostest |
| @subsection cmostest |
| |
| @deffn Command cmostest byte:bit |
| Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status |
| is zero if bit is set, non zero otherwise. This command is available only |
| on platforms that support CMOS. |
| @end deffn |
| |
| |
| @node cmp |
| @subsection cmp |
| |
| @deffn Command cmp file1 file2 |
| Compare the file @var{file1} with the file @var{file2}. If they differ |
| in size, print the sizes like this: |
| |
| @example |
| Differ in size: 0x1234 [foo], 0x4321 [bar] |
| @end example |
| |
| If the sizes are equal but the bytes at an offset differ, then print the |
| bytes like this: |
| |
| @example |
| Differ at the offset 777: 0xbe [foo], 0xef [bar] |
| @end example |
| |
| If they are completely identical, nothing will be printed. |
| @end deffn |
| |
| |
| @node configfile |
| @subsection configfile |
| |
| @deffn Command configfile file |
| Load @var{file} as a configuration file. If @var{file} defines any menu |
| entries, then show a menu containing them immediately. Any environment |
| variable changes made by the commands in @var{file} will not be preserved |
| after @command{configfile} returns. |
| @end deffn |
| |
| |
| @node cpuid |
| @subsection cpuid |
| |
| @deffn Command cpuid [-l] [-p] |
| Check for CPU features. This command is only available on x86 systems. |
| |
| With the @option{-l} option, return true if the CPU supports long mode |
| (64-bit). |
| |
| With the @option{-p} option, return true if the CPU supports Physical |
| Address Extension (PAE). |
| |
| If invoked without options, this command currently behaves as if it had been |
| invoked with @option{-l}. This may change in the future. |
| @end deffn |
| |
| |
| @node crc |
| @subsection crc |
| |
| @deffn Command crc arg @dots{} |
| Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum} |
| (@pxref{hashsum}) for full description. |
| @end deffn |
| |
| |
| @node cryptomount |
| @subsection cryptomount |
| |
| @deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b} |
| Setup access to encrypted device. If necessary, passphrase |
| is requested interactively. Option @var{device} configures specific grub device |
| (@pxref{Naming convention}); option @option{-u} @var{uuid} configures device |
| with specified @var{uuid}; option @option{-a} configures all detected encrypted |
| devices; option @option{-b} configures all geli containers that have boot flag set. |
| |
| GRUB suports devices encrypted using LUKS and geli. Note that necessary modules (@var{luks} and @var{geli}) have to be loaded manually before this command can |
| be used. |
| @end deffn |
| |
| |
| @node date |
| @subsection date |
| |
| @deffn 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. |
| @end deffn |
| |
| |
| @node devicetree |
| @subsection linux |
| |
| @deffn Command devicetree file |
| Load a device tree blob (.dtb) from a filesystem, for later use by a Linux |
| kernel. Does not perform merging with any device tree supplied by firmware, |
| but rather replaces it completely. |
| @ref{GNU/Linux}. |
| @end deffn |
| |
| @node distrust |
| @subsection distrust |
| |
| @deffn Command distrust pubkey_id |
| Remove public key @var{pubkey_id} from GRUB's keyring of trusted keys. |
| @var{pubkey_id} is the last four bytes (eight hexadecimal digits) of |
| the GPG v4 key id, which is also the output of @command{list_trusted} |
| (@pxref{list_trusted}). Outside of GRUB, the key id can be obtained |
| using @code{gpg --fingerprint}). |
| These keys are used to validate signatures when environment variable |
| @code{check_signatures} is set to @code{enforce} |
| (@pxref{check_signatures}), and by some invocations of |
| @command{verify_detached} (@pxref{verify_detached}). @xref{Using |
| digital signatures}, for more information. |
| @end deffn |
| |
| @node drivemap |
| @subsection drivemap |
| |
| @deffn Command drivemap @option{-l}|@option{-r}|[@option{-s}] @ |
| from_drive to_drive |
| Without options, map the drive @var{from_drive} to the drive @var{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 @verb{'${root}'} as a |
| drive specification. |
| |
| With the @option{-s} option, perform the reverse mapping as well, swapping |
| the two drives. |
| |
| With the @option{-l} option, list the current mappings. |
| |
| With the @option{-r} option, reset all mappings to the default values. |
| |
| For example: |
| |
| @example |
| drivemap -s (hd0) (hd1) |
| @end example |
| @end deffn |
| |
| |
| @node echo |
| @subsection echo |
| |
| @deffn Command echo [@option{-n}] [@option{-e}] string @dots{} |
| Display the requested text and, unless the @option{-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 @samp{$@{var@}}. |
| |
| The @option{-e} option enables interpretation of backslash escapes. The |
| following sequences are recognised: |
| |
| @table @code |
| @item \\ |
| backslash |
| |
| @item \a |
| alert (BEL) |
| |
| @item \c |
| suppress trailing new line |
| |
| @item \f |
| form feed |
| |
| @item \n |
| new line |
| |
| @item \r |
| carriage return |
| |
| @item \t |
| horizontal tab |
| |
| @item \v |
| vertical tab |
| @end table |
| |
| When interpreting backslash escapes, backslash followed by any other |
| character will print that character. |
| @end deffn |
| |
| |
| @node eval |
| @subsection eval |
| |
| @deffn Command eval string ... |
| Concatenate arguments together using single space as separator and evaluate |
| result as sequence of GRUB commands. |
| @end deffn |
| |
| |
| @node export |
| @subsection export |
| |
| @deffn Command export envvar |
| Export the environment variable @var{envvar}. Exported variables are visible |
| to subsidiary configuration files loaded using @command{configfile}. |
| @end deffn |
| |
| |
| @node false |
| @subsection false |
| |
| @deffn Command false |
| Do nothing, unsuccessfully. This is mainly useful in control constructs |
| such as @code{if} and @code{while} (@pxref{Shell-like scripting}). |
| @end deffn |
| |
| |
| @node gettext |
| @subsection gettext |
| |
| @deffn Command gettext string |
| Translate @var{string} into the current language. |
| |
| The current language code is stored in the @samp{lang} variable in GRUB's |
| environment (@pxref{lang}). Translation files in MO format are read from |
| @samp{locale_dir} (@pxref{locale_dir}), usually @file{/boot/grub/locale}. |
| @end deffn |
| |
| |
| @node gptsync |
| |