grubby/boot/grub/persistent/docs/15_environment_variables

15 GRUB environment variables
*****************************

GRUB supports environment variables which are rather like those offered
by all Unix-like systems.  Environment variables have a name, which is
unique and is usually a short identifier, and a value, which is an
arbitrary string of characters.  They may be set (*note set::), unset
(*note unset::), or looked up (*note Shell-like scripting::) by name.

   A number of environment variables have special meanings to various
parts of GRUB. Others may be used freely in GRUB configuration files.

15.1 Special environment variables
==================================

These variables have special meaning to GRUB.

15.1.1 biosnum
--------------

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

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

15.1.2 check_signatures
-----------------------

This variable controls whether GRUB enforces digital signature
validation on loaded files.  *Note Using digital signatures::.

15.1.3 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 '>'.

15.1.4 cmdpath
--------------

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

15.1.5 color_highlight
----------------------

This variable contains the "highlight" foreground and background
terminal colors, separated by a slash ('/').  Setting this variable
changes those colors.  For the available color names, *note
color_normal::.

   The default is 'black/light-gray'.

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

15.1.7 config_directory
-----------------------

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

15.1.8 config_file
------------------

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

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

15.1.10 default
---------------

If this variable is set, it identifies a menu entry that should be
selected by default, possibly after a timeout (*note timeout::).  The
entry may be identified by number (starting from 0 at each level of the
hierarchy), by title, or by id.

   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:

     default=example-gnu-linux

   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:

     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

   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' (*note Simple
configuration::), 'grub-set-default', or 'grub-reboot'.

15.1.11 fallback
----------------

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

15.1.12 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'.

15.1.13 gfxpayload
------------------

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

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

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

   This variable is often set by 'GRUB_GFXPAYLOAD_LINUX' (*note Simple
configuration::).

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

15.1.15 grub_cpu
----------------

In normal mode (*note normal::), GRUB sets the 'grub_cpu' variable to
the CPU type for which GRUB was built (e.g.  'i386' or 'powerpc').

15.1.16 grub_platform
---------------------

In normal mode (*note normal::), GRUB sets the 'grub_platform' variable
to the platform for which GRUB was built (e.g.  'pc' or 'efi').

15.1.17 icondir
---------------

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

15.1.18 lang
------------

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

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

15.1.19 locale_dir
------------------

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

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

15.1.20 menu_color_highlight
----------------------------

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

   The default is the value of 'color_highlight' (*note
color_highlight::).

15.1.21 menu_color_normal
-------------------------

This variable contains the foreground and background colors to be used
for non-highlighted menu entries, separated by a slash ('/').  Setting
this variable changes those colors.  For the available color names,
*note color_normal::.

   The default is the value of 'color_normal' (*note color_normal::).

15.1.22 net_<INTERFACE>_boot_file
---------------------------------

*Note Network::.

15.1.23 net_<INTERFACE>_dhcp_server_name
----------------------------------------

*Note Network::.

15.1.24 net_<INTERFACE>_domain
------------------------------

*Note Network::.

15.1.25 net_<INTERFACE>_extensionspath
--------------------------------------

*Note Network::.

15.1.26 net_<INTERFACE>_hostname
--------------------------------

*Note Network::.

15.1.27 net_<INTERFACE>_ip
--------------------------

*Note Network::.

15.1.28 net_<INTERFACE>_mac
---------------------------

*Note Network::.

15.1.29 net_<INTERFACE>_next_server
-----------------------------------

*Note Network::.

15.1.30 net_<INTERFACE>_rootpath
--------------------------------

*Note Network::.

15.1.31 net_default_interface
-----------------------------

*Note Network::.

15.1.32 net_default_ip
----------------------

*Note Network::.

15.1.33 net_default_mac
-----------------------

*Note Network::.

15.1.34 net_default_server
--------------------------

*Note Network::.

15.1.35 pager
-------------

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

15.1.36 prefix
--------------

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

15.1.37 pxe_blksize
-------------------

*Note Network::.

15.1.38 pxe_default_gateway
---------------------------

*Note Network::.

15.1.39 pxe_default_server
--------------------------

*Note Network::.

15.1.40 root
------------

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

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

15.1.41 superusers
------------------

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

15.1.42 theme
-------------

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

   This variable is often set by 'GRUB_THEME' (*note Simple
configuration::).

15.1.43 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' (*note 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' (*note Simple
configuration::).

15.1.44 timeout_style
---------------------

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

15.2 The GRUB environment block
===============================

It is often useful to be able to remember a small amount of information
from one boot to the next.  For example, you might want to set the
default menu entry based on what was selected the last time.  GRUB
deliberately does not implement support for writing files in order to
minimise the possibility of the boot loader being responsible for file
system corruption, so a GRUB configuration file cannot just create a
file in the ordinary way.  However, GRUB provides an "environment block"
which can be used to save a small amount of state.

   The environment block is a preallocated 1024-byte file, which
normally lives in '/boot/grub/grubenv' (although you should not assume
this).  At boot time, the 'load_env' command (*note load_env::) loads
environment variables from it, and the 'save_env' (*note save_env::)
command saves environment variables to it.  From a running system, the
'grub-editenv' utility can be used to edit the environment block.

   For safety reasons, this storage is only available when installed on
a plain disk (no LVM or RAID), using a non-checksumming filesystem (no
ZFS), and using BIOS or EFI functions (no ATA, USB or IEEE1275).

   'grub-mkconfig' uses this facility to implement 'GRUB_SAVEDEFAULT'
(*note Simple configuration::).