These variables have special meaning to GRUB.

biosnum

When chain-loading another boot loader (see Chain-loading), GRUB may need to know what BIOS drive number corresponds to the root device (see root) so that it can set up registers properly. If the biosnum variable is set, it overrides GRUB’s own means of guessing this.

For an alternative approach which also changes BIOS drive mappings for the chain-loaded system, see drivemap.

check_signatures

This variable controls whether GRUB enforces digital signature validation on loaded files. See Using digital signatures.

chosen

When executing a menu entry, GRUB sets the chosen variable to the title of the entry being executed.

If the menu entry is in one or more submenus, then chosen is set to the titles of each of the submenus starting from the top level followed by the title of the menu entry itself, separated by ‘>’.

cmdpath

The location from which core.img was loaded as an absolute directory name (see 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.

color_highlight

This variable contains the “highlight” foreground and background terminal colors, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is ‘black/light-gray’.

color_normal

This variable contains the “normal” foreground and background terminal colors, separated by a slash (‘/’). Setting this variable changes those colors. Each color must be a name from the following list:

• black

• blue

• green

• cyan

• red

• magenta

• brown

• light-gray

• dark-gray

• light-blue

• light-green

• light-cyan

• light-red

• light-magenta

• yellow

• white

The default is ‘light-gray/black’.

The color support support varies from terminal to terminal.

‘morse’ has no color support at all.

‘mda_text’ color support is limited to highlighting by black/white reversal.

‘console’ on ARC, EMU and IEEE1275, ‘serial_*’ and ‘spkmodem’ are governed by terminfo and support only 8 colors if in modes ‘vt100-color’ (default for console on emu), ‘arc’ (default for console on ARC), ‘ieee1275’ (default for console on IEEE1275). When in mode ‘vt100’ then the color support is limited to highlighting by black/white reversal. When in mode ‘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.

‘console’ on EFI and BIOS and ‘vga_text’ support all 16 colors.

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

config_directory

This variable is automatically set by GRUB to the directory part of current configuration file name (see config_file).

config_file

This variable is automatically set by GRUB to the name of configuration file that is being processed by commands configfile (see configfile) or normal (see normal). It is restored to the previous value when command completes.

debug

This variable may be set to enable debugging output from various components of GRUB. The value is a list of debug facility names separated by whitespace or ‘,’, or ‘all’ to enable all available debugging output. The facility names are the first argument to grub_dprintf. Consult source for more details.

default

If this variable is set, it identifies a menu entry that should be selected by default, possibly after a timeout (see 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:

then you can make this the default using:

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 ‘>’. For example, take the following menu structure:

The more recent release of Minix would then be identified as ‘Other platforms>Minix>Version 3.4.0’, or as ‘1>0>0’, or as ‘other>minix>minix-3.4.0’.

This variable is often set by ‘GRUB_DEFAULT’ (see Simple configuration), grub-set-default, or grub-reboot.

fallback

If this variable is set, it identifies a menu entry that should be selected if the default menu entry fails to boot. Entries are identified in the same way as for ‘default’ (see default).

gfxmode

If this variable is set, it sets the resolution used on the ‘gfxterm’ graphical terminal. Note that you can only use modes which your graphics card supports via VESA BIOS Extensions (VBE), so for example native LCD panel resolutions may not be available. The default is ‘auto’, which selects a platform-specific default that should look reasonable. Supported modes can be listed by ‘videoinfo’ command in GRUB.

The resolution may be specified as a sequence of one or more modes, separated by commas (‘,’) or semicolons (‘;’); each will be tried in turn until one is found. Each mode should be either ‘auto’, ‘widthxheight’, or ‘widthxheightxdepth’.

gfxpayload

If this variable is set, it controls the video mode in which the Linux kernel starts up, replacing the ‘vga=’ boot option (see linux). It may be set to ‘text’ to force the Linux kernel to boot in normal text mode, ‘keep’ to preserve the graphics mode set using ‘gfxmode’, or any of the permitted values for ‘gfxmode’ to set a particular graphics mode (see gfxmode).

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

The default is platform-specific. On platforms with a native text mode (such as PC BIOS platforms), the default is ‘text’. Otherwise the default may be ‘auto’ or a specific video mode.

This variable is often set by ‘GRUB_GFXPAYLOAD_LINUX’ (see Simple configuration).

gfxterm_font

If this variable is set, it names a font to use for text on the ‘gfxterm’ graphical terminal. Otherwise, ‘gfxterm’ may use any available font.

grub_cpu

In normal mode (see normal), GRUB sets the ‘grub_cpu’ variable to the CPU type for which GRUB was built (e.g. ‘i386’ or ‘powerpc’).

grub_platform

In normal mode (see normal), GRUB sets the ‘grub_platform’ variable to the platform for which GRUB was built (e.g. ‘pc’ or ‘efi’).

icondir

If this variable is set, it names a directory in which the GRUB graphical menu should look for icons after looking in the theme’s ‘icons’ directory. See Theme file format.

lang

If this variable is set, it names the language code that the gettext command (see gettext) uses to translate strings. For example, French would be named as ‘fr’, and Simplified Chinese as ‘zh_CN’.

grub-mkconfig (see Simple configuration) will try to set a reasonable default for this variable based on the system locale.

locale_dir

If this variable is set, it names the directory where translation files may be found (see gettext), usually /boot/grub/locale. Otherwise, internationalization is disabled.

grub-mkconfig (see Simple configuration) will set a reasonable default for this variable if internationalization is needed and any translation files are available.

menu_color_highlight

This variable contains the foreground and background colors to be used for the highlighted menu entry, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is the value of ‘color_highlight’ (see color_highlight).

menu_color_normal

This variable contains the foreground and background colors to be used for npxe_default_gtimon-highlighted menu entries, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is the value of ‘color_normal’ (see color_normal).

net_<interface>_boot_file

net_<interface>_dhcp_server_name

net_<interface>_domain

net_<interface>_extensionspath

net_<interface>_hostname

net_<interface>_ip

net_<interface>_mac

net_<interface>_next_server

net_<interface>_rootpath

net_default_interface

net_default_ip

net_default_mac

net_default_server

See Network.

pager

If set to ‘1’, pause output after each screenful and wait for keyboard input. The default is not to pause output.

prefix

The location of the ‘/boot/grub’ directory as an absolute file name (see File name syntax). This is normally set by GRUB at startup based on information provided by grub-install. GRUB modules are dynamically loaded from this directory, so it must be set correctly in order for many parts of GRUB to work.

pxe_blksize

pxe_default_gtimeout_styleateway

pxe_default_server

See Network.

root

The root device name (see Device syntax). Any file names that do not specify an explicit device name are read from this device. The default is normally set by GRUB at startup based on the value of ‘prefix’ (see prefix).

For example, if GRUB was installed to the first partition of the first hard disk, then ‘prefix’ might be set to ‘(hd0,msdos1)/boot/grub’ and ‘root’ to ‘hd0,msdos1’.

superusers

This variable may be set to a list of superuser names to enable authentication support. See Security.

theme

This variable may be set to a directory containing a GRUB graphical menu theme. See Theme file format.

This variable is often set by ‘GRUB_THEME’ (see Simple configuration).

timeout

If this variable is set, it specifies the time in seconds to wait for keyboard input before booting the default menu entry. A timeout of ‘0’ means to boot the default entry immediately without displaying the menu; a timeout of ‘-1’ (or unset) means to wait indefinitely.

If ‘timeout_style’ (see timeout_style) is set to ‘countdown’ or ‘hidden’, the timeout is instead counted before the menu is displayed.

This variable is often set by ‘GRUB_TIMEOUT’ (see Simple configuration).

timeout_style

This variable may be set to ‘menu’, ‘countdown’, or ‘hidden’ to control the way in which the timeout (see timeout) interacts with displaying the menu. See the documentation of ‘GRUB_TIMEOUT_STYLE’ (see Simple configuration) for details.