459 lines
14 KiB
Text
459 lines
14 KiB
Text
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::).
|