grub2: Simple configuration
6.1 Simple configuration handling
=================================
The program 'grub-mkconfig' (
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 (
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 (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 (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.
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. 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_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. 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. 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
DONTPRINTYET 'GRUB_DEFAULT', 'fallback' (fallback) and 'default' (*note 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. 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.
Info Catalog
grub2: Configuration
grub2: Shell-like scripting