href="#BIOS-installation">BIOS installation.

In order to install GRUB under a UNIX-like OS (such as GNU), invoke the program grub-install (see Invoking grub-install) as the superuser (root).

The usage is basically very simple. You only need to specify one argument to the program, namely, where to install the boot loader. The argument has to be either a device file (like ‘/dev/hda’). For example, under Linux the following will install GRUB into the MBR of the first IDE disk:

# grub-install /dev/sda

Likewise, under GNU/Hurd, this has the same effect:

# grub-install /dev/hd0

But all the above examples assume that GRUB should put images under the /boot directory. If you want GRUB to put images under a directory other than /boot, you need to specify the option --boot-directory. The typical usage is that you create a GRUB boot floppy with a filesystem. Here is an example:

# mke2fs /dev/fd0
# mount -t ext2 /dev/fd0 /mnt
# mkdir /mnt/boot
# grub-install --boot-directory=/mnt/boot /dev/fd0
# umount /mnt

Some BIOSes have a bug of exposing the first partition of a USB drive as a floppy instead of exposing the USB drive as a hard disk (they call it “USB-FDD” boot). In such cases, you need to install like this:

# losetup /dev/loop0 /dev/sdb1
# mount /dev/loop0 /mnt/usb
# grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0

This install doesn’t conflict with standard install as long as they are in separate directories.

Note that grub-install is actually just a shell script and the real task is done by other tools such as grub-mkimage. Therefore, you may run those commands directly to install GRUB, without using grub-install. Don’t do that, however, unless you are very familiar with the internals of GRUB. Installing a boot loader on a running OS may be extremely dangerous.

On EFI systems for fixed disk install you have to mount EFI System Partition. If you mount it at /boot/efi then you don’t need any special arguments:

# grub-install

Otherwise you need to specify where your EFI System partition is mounted:

# grub-install --efi-directory=/mnt/efi

For removable installs you have to use --removable and specify both --boot-directory and --efi-directory:

# grub-install --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable

4.2 Making a GRUB bootable CD-ROM

GRUB supports the no emulation mode in the El Torito specification⁶. This means that you can use the whole CD-ROM from GRUB and you don’t have to make a floppy or hard disk image file, which can cause compatibility problems.

For booting from a CD-ROM, GRUB uses a special image called cdboot.img, which is concatenated with core.img. The core.img used for this should be built with at least the ‘iso9660’ and ‘biosdisk’ modules. Your bootable CD-ROM will usually also need to include a configuration file grub.cfg and some other GRUB modules.

To make a simple generic GRUB rescue CD, you can use the grub-mkrescue program (see Invoking grub-mkrescue):

$ grub-mkrescue -o grub.iso

You will often need to include other files in your image. To do this, first make a top directory for the bootable image, say, ‘iso’:

$ mkdir iso

Make a directory for GRUB:

$ mkdir -p iso/boot/grub

If desired, make the config file grub.cfg under iso/boot/grub (see Configuration), and copy any files and directories for the disc to the directory iso/.

Finally, make the image:

$ grub-mkrescue -o grub.iso iso

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

The root device will be set up appropriately on entering your grub.cfg configuration file, so you can refer to file names on the CD without needing to use an explicit device name. This makes it easier to produce rescue images that will work on both optical drives and USB mass storage devices.

4.3 The map between BIOS drives and OS devices

If the device map file exists, the GRUB utilities (grub-probe, etc.) read it to map BIOS drives to OS devices. This file consists of lines like this:

(device) file

device is a drive specified in the GRUB syntax (see Device syntax), and file is an OS file, which is normally a device file.

Historically, the device map file was used because GRUB device names had to be used in the configuration file, and they were derived from BIOS drive numbers. The map between BIOS drives and OS devices cannot always be guessed correctly: for example, GRUB will get the order wrong if you exchange the boot sequence between IDE and SCSI in your BIOS.

Unfortunately, even OS device names are not always stable. Modern versions of the Linux kernel may probe drives in a different order from boot to boot, and the prefix (/dev/hd* versus /dev/sd*) may change depending on the driver subsystem in use. As a result, the device map file required frequent editing on some systems.

GRUB avoids this problem nowadays by using UUIDs or file system labels when generating grub.cfg, and we advise that you do the same for any custom menu entries you write. If the device map file does not exist, then the GRUB utilities will assume a temporary device map on the fly. This is often good enough, particularly in the common case of single-disk systems.

However, the device map file is not entirely obsolete yet, and it is used for overriding when current environment is different from the one on boot. Most common case is if you use a partition or logical volume as a disk for virtual machine. You can put any comments in the file if needed, as the GRUB utilities assume that a line is just a comment if the first character is ‘#’.

4.4 BIOS installation

MBR

The partition table format traditionally used on PC BIOS platforms is called the Master Boot Record (MBR) format; this is the format that allows up to four primary partitions and additional logical partitions. With this partition table format, there are two ways to install GRUB: it can be embedded in the area between the MBR and the first partition (called by various names, such as the "boot track", "MBR gap", or "embedding area", and which is usually at least 31 KiB), or the core image can be installed in a file system and a list of the blocks that make it up can be stored in the first sector of that partition.

Each of these has different problems. There is no way to reserve space in the embedding area with complete safety, and some proprietary software is known to use it to make it difficult for users to work around licensing restrictions; and systems are sometimes partitioned without leaving enough space before the first partition. On the other hand, installing to a filesystem means that GRUB is vulnerable to its blocks being moved around by filesystem features such as tail packing, or even by aggressive fsck implementations, so this approach is quite fragile; and this approach can only be used if the /boot filesystem is on the same disk that the BIOS boots from, so that GRUB does not have to rely on guessing BIOS drive numbers.

The GRUB development team generally recommends embedding GRUB before the first partition, unless you have special requirements. You must ensure that the first partition starts at least 31 KiB (63 sectors) from the start of the disk; on modern disks, it is often a performance advantage to align partitions on larger boundaries anyway, so the first partition might start 1 MiB from the start of the disk.

GPT

Some newer systems use the GUID Partition Table (GPT) format. This was specified as part of the Extensible Firmware Interface (EFI), but it can also be used on BIOS platforms if system software supports it; for example, GRUB and GNU/Linux can be used in this configuration. With this format, it is possible to reserve a whole partition for GRUB, called the BIOS Boot Partition. GRUB can then be embedded into that partition without the risk of being overwritten by other software and without being contained in a filesystem which might move its blocks around.

When creating a BIOS Boot Partition on a GPT system, you should make sure that it is at least 31 KiB in size. (GPT-formatted disks are not usually particularly small, so we recommend that you make it larger than the bare minimum, such as 1 MiB, to allow plenty of room for growth.) You must also make sure that it has the proper partition type. Using GNU Parted, you can set this using a command such as the following:

# parted /dev/disk set partition-number bios_grub on

If you are using gdisk, set the partition type to ‘0xEF02’. With partitioning programs that require setting the GUID directly, it should be ‘21686148-6449-6e6f-744e656564454649’.

Caution: Be very careful which partition you select! When GRUB finds a BIOS Boot Partition during installation, it will automatically overwrite part of it. Make sure that the partition does not contain any other data.

5 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.

5.1 How to boot operating systems

GRUB has two distinct boot methods. One of the two is to load an operating system directly, and the other is to chain-load another boot loader which then will load an operating system actually. Generally speaking, the former is more desirable, because you don’t need to install or maintain other boot loaders and GRUB is flexible enough to load an operating system from an arbitrary disk/partition. However, the latter is sometimes required, since GRUB doesn’t support all the existing operating systems natively.

5.1.1 How to boot an OS directly with GRUB

Multiboot (see Motivation in 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 (see Chain-loading).

FIXME: this section is incomplete.

Run the command boot (see boot).

However, DOS and Windows have some deficiencies, so you might have to use more complicated instructions. See DOS/Windows, for more information.

5.1.2 Chain-loading an OS

Operating systems that do not support Multiboot and do not have specific support in GRUB (specific support is available for Linux, FreeBSD, NetBSD and OpenBSD) must be chain-loaded, which involves loading another boot loader and jumping to it in real mode.

The chainloader command (see chainloader) is used to set this up. It is normally also necessary to load some GRUB modules and set the appropriate root device. Putting this together, we get something like this, for a Windows system on the first partition of the first hard disk:

menuentry "Windows" {
	insmod chain
	insmod ntfs
	set root=(hd0,1)
	chainloader +1
}

On systems with multiple hard disks, an additional workaround may be required. See DOS/Windows.

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

5.2 Loopback booting

GRUB is able to read from an image (be it one of CD or HDD) stored on any of its accessible storages (refer to see loopback command). However the OS itself should be able to find its root. This usually involves running a userspace program running before the real root is discovered. This is achieved by GRUB loading a specially made small image and passing it as ramdisk to the kernel. This is achieved by commands kfreebsd_module, knetbsd_module_elf, kopenbsd_ramdisk, initrd (see initrd), initrd16 (see initrd), multiboot_module, multiboot2_module or xnu_ramdisk depending on the loader. Note that for knetbsd the image must be put inside miniroot.kmod and the whole miniroot.kmod has to be loaded. In kopenbsd payload this is disabled by default. Aditionally behaviour of initial ramdisk depends on command line options. Several distributors provide the image for this purpose or it’s integrated in their standard ramdisk and activated by special option. Consult your kernel and distribution manual for more details. Other loaders like appleloader, chainloader (BIOS, EFI, coreboot), freedos, ntldr and plan9 provide no possibility of loading initial ramdisk and as far as author is aware the payloads in question don’t support either initial ramdisk or discovering loopback boot in other way and as such not bootable this way. Please consider alternative boot methods like copying all files from the image to actual partition. Consult your OS documentation for more details

5.3 Some caveats on OS-specific issues

Here, we describe some caveats on several operating systems.

5.3.1 GNU/Hurd

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

Set GRUB’s root device to the same drive as GNU/Hurd’s. The command search --set=root --file /boot/gnumach.gz or similar may help you (see search).

Load the kernel and the modules, like this:

grub> multiboot /boot/gnumach.gz root=device:hd0s1
grub> module  /hurd/ext2fs.static ext2fs --readonly \
                   --multiboot-command-line='${kernel-command-line}' \
                   --host-priv-port='${host-port}' \
                   --device-master-port='${device-port}' \
                   --exec-server-task='${exec-task}' -T typed '${root}' \
                   '$(task-create)' '$(task-resume)'
grub> module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)'

Finally, run the command boot (see boot).

5.3.2 GNU/Linux

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

Set GRUB’s root device to the same drive as GNU/Linux’s. The command search --set=root --file /vmlinuz or similar may help you (see search).
Load the kernel using the command linux (see linux):
```
grub> linux /vmlinuz root=/dev/sda1
```
If you need to specify some kernel parameters, just append them to the command. For example, to set acpi to ‘off’, do this:
```
grub> linux /vmlinuz root=/dev/sda1 acpi=off
```
See the documentation in the Linux source tree for complete information on the available options.

With linux GRUB uses 32-bit protocol. Some BIOS services like APM or EDD aren’t available with this protocol. In this case you need to use linux16
```
grub> linux16 /vmlinuz root=/dev/sda1 acpi=off
```
If you use an initrd, execute the command initrd (see initrd) after linux:
```
grub> initrd /initrd
```
If you used linux16 you need to use initrd16:
```
grub> initrd16 /initrd
```
Finally, run the command boot (see boot).

Caution: If you use an initrd and specify the ‘mem=’ option to the kernel to let it use less than actual memory size, you will also have to specify the same memory size to GRUB. To let GRUB know the size, run the command uppermem before loading the kernel. See uppermem, for more information.

5.3.3 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 boot.

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:
```
grub> insmod part_bsd
grub> set root=(hd0,netbsd1)
```
For a disk with a GUID Partition Table (GPT), and assuming that the NetBSD root partition is the third GPT partition, do this:
```
grub> insmod part_gpt
grub> set root=(hd0,gpt3)
```
Load the kernel using the command knetbsd:
```
grub> knetbsd /netbsd
```
Various options may be given to 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:
```
grub> knetbsd /netbsd -s -v
```
If needed, load kernel modules with the command knetbsd_module_elf. A typical example is the module for the root file system:
```
grub> knetbsd_module_elf /stand/amd64/6.0/modules/ffs/ffs.kmod
```
Finally, run the command boot (see boot).

5.3.4 DOS/Windows

GRUB cannot boot DOS or Windows directly, so you must chain-load them (see Chain-loading). However, their boot loaders have some critical deficiencies, so it may not work to just chain-load them. To overcome the problems, GRUB provides you with two helper functions.

If you have installed DOS (or Windows) on a non-first hard disk, you have to use the disk swapping technique, because that OS cannot boot from any disks but the first one. The workaround used in GRUB is the command drivemap (see drivemap), like this:

drivemap -s (hd0) (hd1)

This performs a virtual swap between your first and second hard drive.

Caution: This is effective only if DOS (or Windows) uses BIOS to access the swapped disks. If that OS uses a special driver for the disks, this probably won’t work.

Another problem arises if you installed more than one set of DOS/Windows onto one disk, because they could be confused if there are more than one primary partitions for DOS/Windows. Certainly you should avoid doing this, but there is a solution if you do want to do so. Use the partition hiding/unhiding technique.

If GRUB hides a DOS (or Windows) partition (see parttool), DOS (or Windows) will ignore the partition. If GRUB unhides a DOS (or Windows) partition, DOS (or Windows) will detect the partition. Thus, if you have installed DOS (or Windows) on the first and the second partition of the first hard disk, and you want to boot the copy on the first partition, do the following:

parttool (hd0,1) hidden-
parttool (hd0,2) hidden+
set root=(hd0,1)
chainloader +1
parttool ${root} boot+
boot

6 Writing your own configuration file

GRUB is configured using grub.cfg, usually located under /boot/grub. This file is quite flexible, but most users will not need to write the whole thing by hand.

6.1 Simple configuration handling

The program grub-mkconfig (see Invoking grub-mkconfig) generates grub.cfg files suitable for most cases. It is suitable for use when upgrading a distribution, and will discover available kernels and attempt to generate menu entries for them.

grub-mkconfig does have some limitations. While adding extra custom menu entries to the end of the list can be done by editing /etc/grub.d/40_custom or creating /boot/grub/custom.cfg, changing the order of menu entries or changing their titles may require making complex changes to shell scripts stored in /etc/grub.d/. This may be improved in the future. In the meantime, those who feel that it would be easier to write grub.cfg directly are encouraged to do so (see Booting, and Shell-like scripting), and to disable any system provided by their distribution to automatically run grub-mkconfig.

The file /etc/default/grub controls the operation of grub-mkconfig. It is sourced by a shell script, and so must be valid POSIX shell input; normally, it will just be a sequence of ‘KEY=value’ lines, but if the value contains spaces or other special characters then it must be quoted. For example:

GRUB_TERMINAL_INPUT="console serial"

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

‘GRUB_DEFAULT’

The default menu entry. This may be a number, in which case it identifies the Nth entry in the generated menu counted from zero, or the title of a menu entry, or the special string ‘saved’. Using the 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:

menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux {
	...
}

then you can make this the default using:

GRUB_DEFAULT=example-gnu-linux

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 ‘saved’, then the default menu entry will be that saved by ‘GRUB_SAVEDEFAULT’ or grub-set-default. This relies on the environment block, which may not be available in all situations (see Environment block).

The default is ‘0’.

‘GRUB_SAVEDEFAULT’

If this option is set to ‘true’, then, when an entry is selected, save it as a new default entry for use by future runs of GRUB. This is only useful if ‘GRUB_DEFAULT=saved’; it is a separate option because ‘GRUB_DEFAULT=saved’ is useful without this option, in conjunction with grub-set-default. Unset by default. This option relies on the environment block, which may not be available in all situations (see Environment block).

‘GRUB_TIMEOUT’

Boot the default entry this many seconds after the menu is displayed, unless a key is pressed. The default is ‘5’. Set to ‘0’ to boot immediately without displaying the menu, or to ‘-1’ to wait indefinitely.

If ‘GRUB_TIMEOUT_STYLE’ is set to ‘countdown’ or ‘hidden’, the timeout is instead counted before the menu is displayed.

‘GRUB_TIMEOUT_STYLE’

If this option is unset or set to ‘menu’, then GRUB will display the menu and then wait for the timeout set by ‘GRUB_TIMEOUT’ to expire before booting the default entry. Pressing a key interrupts the timeout.

If this option is set to ‘countdown’ or ‘hidden’, then, before displaying the menu, GRUB will wait for the timeout set by ‘GRUB_TIMEOUT’ to expire. If 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 ‘countdown’ case, it will show a one-line indication of the remaining time.

‘GRUB_DEFAULT_BUTTON’

‘GRUB_TIMEOUT_BUTTON’

‘GRUB_TIMEOUT_STYLE_BUTTON’

‘GRUB_BUTTON_CMOS_ADDRESS’

Variants of the corresponding variables without the ‘_BUTTON’ suffix, used to support vendor-specific power buttons. See Vendor power-on keys.

‘GRUB_DISTRIBUTOR’

Set by distributors of GRUB to their identifying name. This is used to generate more informative menu entry titles.

‘GRUB_TERMINAL_INPUT’

Select the terminal input device. You may select multiple devices here, separated by spaces.

Valid terminal input names depend on the platform, but may include ‘console’ (native platform console), ‘serial’ (serial terminal), ‘serial_<port>’ (serial terminal with explicit port selection), ‘at_keyboard’ (PC AT keyboard), or ‘usb_keyboard’ (USB keyboard using the HID Boot Protocol, for cases where the firmware does not handle this).

The default is to use the platform’s native terminal input.

‘GRUB_TERMINAL_OUTPUT’

Select the terminal output device. You may select multiple devices here, separated by spaces.

Valid terminal output names depend on the platform, but may include ‘console’ (native platform console), ‘serial’ (serial terminal), ‘serial_<port>’ (serial terminal with explicit port selection), ‘gfxterm’ (graphics-mode output), ‘vga_text’ (VGA text output), ‘mda_text’ (MDA text output), ‘morse’ (Morse-coding using system beeper) or ‘spkmodem’ (simple data protocol using system speaker).

‘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 ‘spkmodem-recv’ from ‘util/spkmodem-recv.c’ and run:

parecord --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv

The default is to use the platform’s native terminal output.

‘GRUB_TERMINAL’

If this option is set, it overrides both ‘GRUB_TERMINAL_INPUT’ and ‘GRUB_TERMINAL_OUTPUT’ to the same value.

‘GRUB_SERIAL_COMMAND’

A command to configure the serial port when using the serial console. See serial. Defaults to ‘serial’.

‘GRUB_CMDLINE_LINUX’

Command-line arguments to add to menu entries for the Linux kernel.

‘GRUB_CMDLINE_LINUX_DEFAULT’

Unless ‘GRUB_DISABLE_RECOVERY’ is set to ‘true’, two menu entries will be generated for each Linux kernel: one default entry and one entry for recovery mode. This option lists command-line arguments to add only to the default menu entry, after those listed in ‘GRUB_CMDLINE_LINUX’.

‘GRUB_CMDLINE_NETBSD’

‘GRUB_CMDLINE_NETBSD_DEFAULT’

As ‘GRUB_CMDLINE_LINUX’ and ‘GRUB_CMDLINE_LINUX_DEFAULT’, but for NetBSD.

‘GRUB_CMDLINE_GNUMACH’

As ‘GRUB_CMDLINE_LINUX’, but for GNU Mach.

‘GRUB_CMDLINE_XEN’

‘GRUB_CMDLINE_XEN_DEFAULT’

The values of these options are passed to Xen hypervisor Xen menu entries, for all respectively normal entries.

‘GRUB_CMDLINE_LINUX_XEN_REPLACE’

‘GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT’

The values of these options replace the values of ‘GRUB_CMDLINE_LINUX’ and ‘GRUB_CMDLINE_LINUX_DEFAULT’ for Linux and Xen menu entries.

‘GRUB_DISABLE_LINUX_UUID’

Normally, grub-mkconfig will generate menu entries that use universally-unique identifiers (UUIDs) to identify the root filesystem to the Linux kernel, using a ‘root=UUID=...’ kernel parameter. This is usually more reliable, but in some cases it may not be appropriate. To disable the use of UUIDs, set this option to ‘true’.

‘GRUB_DISABLE_RECOVERY’

If this option is set to ‘true’, disable the generation of recovery mode menu entries.

‘GRUB_DISABLE_UUID’

Normally, grub-mkconfig will generate menu entries that use universally-unique identifiers (UUIDs) to identify various filesystems to search for files. This is usually more reliable, but in some cases it may not be appropriate. To disable this use of UUIDs, set this option to ‘true’.

‘GRUB_VIDEO_BACKEND’

If graphical video support is required, either because the ‘gfxterm’ graphical terminal is in use or because ‘GRUB_GFXPAYLOAD_LINUX’ is set, then grub-mkconfig will normally load all available GRUB video drivers and use the one most appropriate for your hardware. If you need to override this for some reason, then you can set this option.

After grub-install has been run, the available video drivers are listed in /boot/grub/video.lst.

‘GRUB_GFXMODE’

Set the resolution used on the ‘gfxterm’ graphical terminal. Note that you can only use modes which your graphics card supports via VESA BIOS Extensions (VBE), so for example native LCD panel resolutions may not be available. The default is ‘auto’, which tries to select a preferred resolution. See gfxmode.

‘GRUB_BACKGROUND’

Set a background image for use with the ‘gfxterm’ graphical terminal. The value of this option must be a file readable by GRUB at boot time, and it must end with .png, .tga, .jpg, or .jpeg. The image will be scaled if necessary to fit the screen.

‘GRUB_THEME’

Set a theme for use with the ‘gfxterm’ graphical terminal.

‘GRUB_GFXPAYLOAD_LINUX’

Set to ‘text’ to force the Linux kernel to boot in normal text mode, ‘keep’ to preserve the graphics mode set using ‘GRUB_GFXMODE’, ‘widthxheight’[‘xdepth’] to set a particular graphics mode, or a sequence of these separated by commas or semicolons to try several modes in sequence. See gfxpayload.

Depending on your kernel, your distribution, your graphics card, and the phase of the moon, note that using this option may cause GNU/Linux to suffer from various display problems, particularly during the early part of the boot sequence. If you have problems, set this option to ‘text’ and GRUB will tell Linux to boot in normal text mode.

‘GRUB_DISABLE_OS_PROBER’

Normally, grub-mkconfig will try to use the external os-prober program, if installed, to discover other operating systems installed on the same system and generate appropriate menu entries for them. Set this option to ‘true’ to disable this.

‘GRUB_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>

‘GRUB_DISABLE_SUBMENU’

Normally, 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 os-prober first entry will be put on top level and all others in submenu. If this option is set to ‘y’, flat menu with all entries on top level will be generated instead. Changing this option will require changing existing values of ‘GRUB_DEFAULT’, ‘fallback’ (see fallback) and ‘default’ (see default) environment variables as well as saved default entry using grub-set-default and value used with grub-reboot.

‘GRUB_ENABLE_CRYPTODISK’

If set to ‘y’, grub-mkconfig and 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.

‘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 play.

‘GRUB_BADRAM’

If this option is set, GRUB will issue a badram command to filter out specified regions of RAM.

‘GRUB_PRELOAD_MODULES’

This option may be set to a list of GRUB module names separated by spaces. Each module will be loaded as early as possible, at the start of grub.cfg.

The following options are still accepted for compatibility with existing configurations, but have better replacements:

‘GRUB_HIDDEN_TIMEOUT’

Wait this many seconds before displaying the menu. If ESC is pressed during that time, display the menu and wait for input according to ‘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 ‘GRUB_TIMEOUT’ before booting the default entry.

If you set ‘GRUB_HIDDEN_TIMEOUT’, you should also set ‘GRUB_TIMEOUT=0’ so that the menu is not displayed at all unless ESC is pressed.

This option is unset by default, and is deprecated in favour of the less confusing ‘GRUB_TIMEOUT_STYLE=countdown’ or ‘GRUB_TIMEOUT_STYLE=hidden’.

‘GRUB_HIDDEN_TIMEOUT_QUIET’

In conjunction with ‘GRUB_HIDDEN_TIMEOUT’, set this to ‘true’ to suppress the verbose countdown while waiting for a key to be pressed before displaying the menu.

This option is unset by default, and is deprecated in favour of the less confusing ‘GRUB_TIMEOUT_STYLE=countdown’.

‘GRUB_HIDDEN_TIMEOUT_BUTTON’

Variant of ‘GRUB_HIDDEN_TIMEOUT’, used to support vendor-specific power buttons. See Vendor power-on keys.

This option is unset by default, and is deprecated in favour of the less confusing ‘GRUB_TIMEOUT_STYLE=countdown’ or ‘GRUB_TIMEOUT_STYLE=hidden’.

For more detailed customisation of grub-mkconfig’s output, you may edit the scripts in /etc/grub.d directly. /etc/grub.d/40_custom is particularly useful for adding entire custom menu entries; simply type the menu entries you want to add at the end of that file, making sure to leave at least the first two lines intact.

6.2 Writing full configuration files directly

grub.cfg is written in GRUB’s built-in scripting language, which has a syntax quite similar to that of GNU Bash and other Bourne shell derivatives.

Words

A word is a sequence of characters considered as a single unit by GRUB. Words are separated by metacharacters, which are the following plus space, tab, and newline:

{ } | & $ ; < >

Quoting may be used to include metacharacters in words; see below.

Reserved words

Reserved words have a special meaning to GRUB. The following words are recognised as reserved when unquoted and either the first word of a simple command or the third word of a for command:

! [[ ]] { }
case do done elif else esac fi for function
if in menuentry select then time until while

Not all of these reserved words have a useful purpose yet; some are reserved for future expansion.

Quoting

Quoting is used to remove the special meaning of certain characters or words. It can be used to treat metacharacters as part of a word, to prevent reserved words from being recognised as such, and to prevent variable expansion.

There are three quoting mechanisms: the escape character, single quotes, and double quotes.

A non-quoted backslash (\) is the escape character. It preserves the literal value of the next character that follows, with the exception of newline.

Enclosing characters in single quotes preserves the literal value of each character within the quotes. A single quote may not occur between single quotes, even when preceded by a backslash.

Enclosing characters in double quotes preserves the literal value of all characters within the quotes, with the exception of ‘$’ and ‘\’. The ‘$’ character retains its special meaning within double quotes. The backslash retains its special meaning only when followed by one of the following characters: ‘$’, ‘"’, ‘\’, or newline. A backslash-newline pair is treated as a line continuation (that is, it is removed from the input stream and effectively ignored⁷). A double quote may be quoted within double quotes by preceding it with a backslash.

Variable expansion

The ‘$’ character introduces variable expansion. The variable name to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from characters immediately following it which could be interpreted as part of the name.

Normal variable names begin with an alphabetic character, followed by zero or more alphanumeric characters. These names refer to entries in the GRUB environment (see Environment).

Positional variable names consist of one or more digits. They represent parameters passed to function calls, with ‘$1’ representing the first parameter, and so on.

The special variable name ‘?’ expands to the exit status of the most recently executed command. When positional variable names are active, other special variable names ‘@’, ‘*’ and ‘#’ are defined and they expand to all positional parameters with necessary quoting, positional parameters without any quoting, and positional parameter count respectively.

Comments

A word beginning with ‘#’ causes that word and all remaining characters on that line to be ignored.

Simple commands

A simple command is a sequence of words separated by spaces or tabs and terminated by a semicolon or a newline. The first word specifies the command to be executed. The remaining words are passed as arguments to the invoked command.

The return value of a simple command is its exit status. If the reserved word ! precedes the command, then the return value is instead the logical negation of the command’s exit status.

Compound commands

A compound command is one of the following:

for name in word …; do list; done: The list of words following in is expanded, generating a list of items. The variable name is set to each element of this list in turn, and list is executed each time. The return value is the exit status of the last command that executes. If the expansion of the items following in results in an empty list, no commands are executed, and the return status is 0.
if list; then list; [elif list; then list;] … [else list;] fi: The if list is executed. If its exit status is zero, the then list is executed. Otherwise, each elif list is executed in turn, and if its exit status is zero, the corresponding then list is executed and the command completes. Otherwise, the else list is executed, if present. The exit status is the exit status of the last command executed, or zero if no condition tested true.
while cond; do list; done
until cond; do list; done: The while command continuously executes the do list as long as the last command in cond returns an exit status of zero. The until command is identical to the while command, except that the test is negated; the do list is executed as long as the last command in cond returns a non-zero exit status. The exit status of the while and until commands is the exit status of the last do list command executed, or zero if none was executed.
function name { command; … }: This defines a function named name. The body of the function is the list of commands within braces, each of which must be terminated with a semicolon or a newline. This list of commands will be executed whenever name is specified as the name of a simple command. Function definitions do not affect the exit status in $?. When executed, the exit status of a function is the exit status of the last command executed in the body.
menuentry title [--class=class …] [--users=users] [--unrestricted] [--hotkey=key] [--id=id] { command; … }: See menuentry.

Built-in Commands

Some built-in commands are also provided by GRUB script to help script writers perform actions that are otherwise not possible. For example, these include commands to jump out of a loop without fully completing it, etc.

break [n]: Exit from within a for, while, or until loop. If n is specified, break n levels. n must be greater than or equal to 1. If n is greater than the number of enclosing loops, all enclosing loops are exited. The return value is 0 unless n is not greater than or equal to 1.
continue [n]: Resume the next iteration of the enclosing for, while or until loop. If n is specified, resume at the nth enclosing loop. n must be greater than or equal to 1. If n is greater than the number of enclosing loops, the last enclosing loop (the top-level loop) is resumed. The return value is 0 unless n is not greater than or equal to 1.
return [n]: Causes a function to exit with the return value specified by n. If n is omitted, the return status is that of the last command executed in the function body. If used outside a function the return status is false.
setparams [arg] …: Replace positional parameters starting with $1 with arguments to setparams.
shift [n]: The positional parameters from n+1 … are renamed to $1…. Parameters represented by the numbers $# down to $#-n+1 are unset. n must be a non-negative number less than or equal to $#. If n is 0, no parameters are changed. If n is not given, it is assumed to be 1. If n is greater than $#, the positional parameters are not changed. The return status is greater than zero if n is greater than $# or less than zero; otherwise 0.

6.3 Multi-boot manual config

Currently autogenerating config files for multi-boot environments depends on os-prober and has several shortcomings. While fixing it is scheduled for the next release, meanwhile you can make use of the power of GRUB syntax and do it yourself. A possible configuration is detailed here, feel free to adjust to your needs.

First create a separate GRUB partition, big enough to hold GRUB. Some of the following entries show how to load OS installer images from this same partition, for that you obviously need to make the partition large enough to hold those images as well. Mount this partition on/mnt/boot and disable GRUB in all OSes and manually install self-compiled latest GRUB with:

grub-install --boot-directory=/mnt/boot /dev/sda

In all the OSes install GRUB tools but disable installing GRUB in bootsector, so you’ll have menu.lst and grub.cfg available for use. Also disable os-prober use by setting:

GRUB_DISABLE_OS_PROBER=true

in /etc/default/grub

Then write a grub.cfg (/mnt/boot/grub/grub.cfg):

menuentry "OS using grub2" {
   insmod xfs
   search --set=root --label OS1 --hint hd0,msdos8
   configfile /boot/grub/grub.cfg
}

menuentry "OS using grub2-legacy" {
   insmod ext2
   search --set=root --label OS2 --hint hd0,msdos6
   legacy_configfile /boot/grub/menu.lst
}

menuentry "Windows XP" {
   insmod ntfs
   search --set=root --label WINDOWS_XP --hint hd0,msdos1
   ntldr /ntldr
}

menuentry "Windows 7" {
   insmod ntfs
   search --set=root --label WINDOWS_7 --hint hd0,msdos2
   ntldr /bootmgr
}

menuentry "FreeBSD" {
          insmod zfs
          search --set=root --label freepool --hint hd0,msdos7
          kfreebsd /freebsd@/boot/kernel/kernel
          kfreebsd_module_elf /freebsd@/boot/kernel/opensolaris.ko
          kfreebsd_module_elf /freebsd@/boot/kernel/zfs.ko
          kfreebsd_module /freebsd@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache
          set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd
          set kFreeBSD.hw.psm.synaptics_support=1
}

menuentry "experimental GRUB" {
          search --set=root --label GRUB --hint hd0,msdos5
          multiboot /experimental/grub/i386-pc/core.img
}

menuentry "Fedora 16 installer" {
          search --set=root --label GRUB --hint hd0,msdos5
          linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280x800
          initrd /fedora/initrd.img
}

menuentry "Fedora rawhide installer" {
          search --set=root --label GRUB --hint hd0,msdos5
          linux /fedora/vmlinuz repo=ftp://mirror.switch.ch/mirror/fedora/linux/development/rawhide/x86_64 lang=en_US keymap=sg resolution=1280x800
          initrd /fedora/initrd.img
}

menuentry "Debian sid installer" {
          search --set=root --label GRUB --hint hd0,msdos5
          linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz
          initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd.gz
}

Notes:

Argument to search after –label is FS LABEL. You can also use UUIDs with –fs-uuid UUID instead of –label LABEL. You could also use direct root=hd0,msdosX but this is not recommended due to device name instability.

6.4 Embedding a configuration file into GRUB

GRUB supports embedding a configuration file directly into the core image, so that it is loaded before entering normal mode. This is useful, for example, when it is not straightforward to find the real configuration file, or when you need to debug problems with loading that file. grub-install uses this feature when it is not using BIOS disk functions or when installing to a different disk from the one containing /boot/grub, in which case it needs to use the search command (see search) to find /boot/grub.

To embed a configuration file, use the -c option to grub-mkimage. The file is copied into the core image, so it may reside anywhere on the file system, and may be removed after running grub-mkimage.

After the embedded configuration file (if any) is executed, GRUB will load the ‘normal’ module (see normal), which will then read the real configuration file from $prefix/grub.cfg. By this point, the root variable will also have been set to the root device name. For example, prefix might be set to ‘(hd0,1)/boot/grub’, and root might be set to ‘hd0,1’. Thus, in most cases, the embedded configuration file only needs to set the prefix and root variables, and then drop through to GRUB’s normal processing. A typical example of this

• 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

• GNU/Hurd:
• GNU/Linux:
• NetBSD:
• DOS/Windows:

• 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