5.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 title 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 {
...
}
then you can make this the default using:
GRUB_DEFAULT='Example GNU/Linux distribution'
If you set this to ‘saved’, then the default menu entry will be that
saved by ‘GRUB_SAVEDEFAULT’, grub-set-default, or
grub-reboot.
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 or grub-reboot. 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.
- ‘GRUB_HIDDEN_TIMEOUT’
- Wait this many seconds for a key to be pressed before displaying the menu.
If no key is pressed during that time, display the menu for the number of
seconds specified in GRUB_TIMEOUT before booting the default entry. We expect
that most people who use GRUB_HIDDEN_TIMEOUT will want to have GRUB_TIMEOUT set
to ‘0’ so that the menu is not displayed at all unless a key is pressed.
Unset by default.
- ‘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. Unset by default.
- ‘GRUB_DEFAULT_BUTTON’
- ‘GRUB_TIMEOUT_BUTTON’
- ‘GRUB_HIDDEN_TIMEOUT_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’ (PC BIOS and EFI consoles), ‘serial’ (serial terminal),
‘ofconsole’ (Open Firmware console), ‘at_keyboard’ (PC AT
keyboard, mainly useful with Coreboot), 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’ (PC BIOS and EFI consoles), ‘serial’ (serial terminal),
‘gfxterm’ (graphics-mode output), ‘ofconsole’ (Open Firmware
console), or ‘vga_text’ (VGA text output, mainly useful with Coreboot).
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 appended to the values of
‘GRUB_CMDLINE_LINUX’ and ‘GRUB_CMDLINE_LINUX_DEFAULT’ for Linux
and Xen menu 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. 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_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.
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.