Next: , Up: Configuration   [Contents][Index]

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:


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


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


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.


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.


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.


Variants of the corresponding variables without the ‘_BUTTON’ suffix, used to support vendor-specific power buttons. See Vendor power-on keys.


Set by distributors of GRUB to their identifying name. This is used to generate more informative menu entry titles.


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.


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.


If this option is set, it overrides both ‘GRUB_TERMINAL_INPUT’ and ‘GRUB_TERMINAL_OUTPUT’ to the same value.


A command to configure the serial port when using the serial console. See serial. Defaults to ‘serial’.


Command-line arguments to add to menu entries for the Linux kernel.


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




As ‘GRUB_CMDLINE_LINUX’, but for GNU Mach.


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.


The values of these options replace the values of ‘GRUB_CMDLINE_LINUX’ and ‘GRUB_CMDLINE_LINUX_DEFAULT’ for Linux and Xen menu entries.


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


If this option is set to ‘true’, disable the generation of recovery mode menu entries.


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.


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.


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.


Set a theme for use with the ‘gfxterm’ graphical terminal.


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.


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.


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.


If this option is set, GRUB will issue a badram command to filter out specified regions of RAM.


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.

Next: , Up: Configuration   [Contents][Index]