Mastering Grub – Part 2 – Grub Configurations

1. Grub Configurations

GRUB is configured using ‘grub.cfg’, usually located under ‘/boot/grub’. This file is quite flexible, but most users will not need to write the whole thing by hand.

1.1  Simple configuration handling

The program ‘grub2-mkconfig’ generates ‘grub.cfg’ upgrading a distribution, and will discover available kernels and attempt to generate menu entries for them.

‘grub2-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/grub2/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 , and to disable any system provided by their distribution to automatically run ‘grub2-mkconfig’.

The ‘grub2-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:


     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  ‘grub2-set-default’.  This relies on the environment block, which may not be available in all situations.

    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 ‘grub2-set-default’.  Unset by default.  This  option relies on the environment block, which may not be available  in all situations


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.


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.


Variants of the corresponding variables without the ‘_BUTTON’ suffix, used to support vendor-specific power buttons.  *Note 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’ (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.


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.


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.  *Note 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 passed to Xen hypervisor Xen menu entries, for all respectively normal 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, ‘grub2-mkconfig’ will generate menu entries that use universally-unique identifiers (UUIDs) to identify the root      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 ‘grub2-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 ‘grub2-install’ has been run, the available video drivers are listed in ‘/boot/grub2/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.  *Note gfxmode::.


     Set a background image for use with the ‘gfxterm’ graphical terminal.  The value of this option must be a 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.  *Note 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, ‘grub2-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.


     List of space-separated FS UUIDs of os-prober output.  For efi chainloaders it’s <UUID>@<EFI


     Normally, ‘grub2-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 ‘GRUB_DEFAULT’, ‘fallback’ (*note fallback::) and ‘default’ (*note default::) environment variables as well as saved default entry using ‘grub2-set-default’ and value used with ‘grub2-reboot’.


     If set to ‘y’, ‘grub2-mkconfig’ and ‘grub2-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.


     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


     If this option is set, GRUB will issue a *note 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’.

The following options are still accepted for compatibility with existing configurations, but have better replacements:


     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.  *Note 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 ‘grub2-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  leave at least the first two lines intact.

1.2 Multi-boot manual config

Currently autogenerating config files for multi-boot environments depends on os-prober and has several shortcomings.  While fixing it is scheduled for the next release, meanwhile you can make use of the power of GRUB syntax and do it yourself.  A possible configuration is detailed here, feel free to adjust to your needs.

First create a separate GRUB partition, big enough to hold GRUB. Some of the following entries show how to load OS installer images from this same partition, for that you obviously need to make the partition large
enough to hold those images as well.  Mount this partition on/mnt/boot and disable GRUB in all OSes and manually install self-compiled latest GRUB with:

   ‘grub2-install –boot-directory=/mnt/boot /dev/sda’

In all the OSes install GRUB tools but disable installing GRUB in bootsector, so you’ll have menu.lst and grub.cfg available for use. Also disable os-prober use by setting:

   ‘GRUB_DISABLE_OS_PROBER=true’    in /etc/default/grub

Then write a grub.cfg (/mnt/boot/grub2/grub.cfg):

 menuentry “OS using grub2” {
   insmod xfs
   search –set=root –label OS1 –hint hd0,msdos8
   config }
 menuentry “OS using grub2-legacy” {
   insmod ext2
   search –set=root –label OS2 –hint hd0,msdos6
   legacy_config }
 menuentry “Windows XP” {
   insmod ntfs
   search –set=root –label WINDOWS_XP –hint hd0,msdos1
   ntldr /ntldr }
 menuentry “Windows 7” {
   insmod ntfs
   search –set=root –label WINDOWS_7 –hint hd0,msdos2
   ntldr /bootmgr }
 menuentry “FreeBSD” { insmod zfs search –set=root –label freepool –hint hd0,msdos7 kfreebsd /freebsd@/boot/kernel/kernel kfreebsd_module_elf /freebsd@/boot/kernel/opensolaris.ko kfreebsd_module_elf /freebsd@/boot/kernel/zfs.ko kfreebsd_module /freebsd@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd set kFreeBSD.hw.psm.synaptics_support=1 }
 menuentry “experimental GRUB” { search –set=root –label GRUB –hint hd0,msdos5 multiboot /experimental/grub/i386-pc/core.img }
 menuentry “Fedora 16 installer” { search –set=root –label GRUB –hint hd0,msdos5 linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280×800 initrd /fedora/initrd.img }
 menuentry “Fedora rawhide installer” { search –set=root –label GRUB –hint hd0,msdos5 linux /fedora/vmlinuz repo= lang=en_US keymap=sg resolution=1280×800 initrd /fedora/initrd.img }
 menuentry “Debian sid installer” { search –set=root –label GRUB –hint hd0,msdos5 linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd.gz }

   Notes:    * Argument to search after -label is FS LABEL. You can also use UUIDs with -fs-uuid UUID instead of -label LABEL. You could also use direct ‘root=hd0,msdosX’ but this is not recommended due to device name instability.

1.3 Embedding a configuration

GRUB supports embedding a configuration image, so that it is loaded before entering normal mode.  This is useful, for example, when it is not straightforward to find the real configuration

functions or when installing to a different disk from the one containing ‘/boot/grub’, in which case it needs to use the ‘search’ command (*note search::) to find ‘/boot/grub’.

To embed a configuration file, use the ‘-c’ option to ‘grub2-mkimage’.  The file is copied into the core image, so it may reside anywhere on the file system, and may be removed after running ‘grub2-mkimage’.

After the embedded configuration file (if any) is executed, GRUB will load the ‘normal’ module , which will then read the real configuration file from ‘$prefix/grub.cfg’.  By this point, the ‘root’ variable will also have been set to the root device name.  For example,’prefix’ might be set to ‘(hd0,1)/boot/grub’, and ‘root’ might be set to ‘hd0,1’.  Thus, in most cases, the embedded configuration file only needs to set the ‘prefix’ and ‘root’ variables, and then drop through to GRUB’s normal processing.  A typical example of this might look like this:

search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root set prefix=($root)/boot/grub

(The ‘search_fs_uuid’ module must be included in the core image for this example to work.)

In more complex cases, it may be useful to read other configuration files directly from the embedded configuration file.  This allows such things as reading  directory other than that where GRUB’s loadable modules are installed.  To do this, include the ‘config image, and embed a configuration  to load another ‘echo’, ‘search_label’, and ‘test’ modules to be included in the core image:

 search.fs_label grub root if [ -e /boot/grub2/example/test1.cfg ]; then
    set prefix=($root)/boot/grub
    config else
    if [ -e /boot/grub2/example/test2.cfg ]; then
   set prefix=($root)/boot/grub
   echo “Could not find an example configuration
    fi fi

The embedded configuration directly, but may only read them from elsewhere using ‘config

2. Theme Elements


The GRUB graphical menu supports themes that can customize the layout and appearance of the GRUB boot menu.  The theme is configured through a plain text (including the boot menu, timeout progress bar, and text messages) as well as the appearance using colors, fonts, and images.  Example is available in docs/example_theme.txt

2.1 Colors

Colors can be specified in several ways:

* HTML-style “#RRGGBB” or “#RGB” format, where *R*, *G*, and *B* are hexadecimal digits (e.g., “#8899FF”)
* as comma-separated decimal RGB values (e.g., “128, 128, 255”)
* with “SVG 1.0 color names” (e.g., “cornflowerblue”) which must be specified in lowercase.

2.2 Fonts

The fonts GRUB uses “PFF2 font format” bitmap fonts.  Fonts are specified with full font names.  Currently there is no provision for a list of fonts, or deriving one font from another.  Fonts are loaded with the “loadfont” command in GRUB.  To see the list of loaded fonts, execute the “lsfonts” command.  If there are too many fonts to fit on screen, do “set pager=1” before executing “lsfonts”.

2.3 Progress Bar

Progress bars are used to display the remaining time before GRUB boots the default menu entry.  To create a progress bar that will display the remaining time before automatic boot, simply create a “progress_bar” component with the id “__timeout__”.  This indicates to GRUB that the progress bar should be updated as time passes, and it should be made invisible if the countdown to automatic boot is interrupted by the user.

Progress bars may optionally have text displayed on them.  This text is controlled by variable “text” which contains a printf template with the only argument %d is the number of seconds remaining.  Additionally
special values “@TIMEOUT_NOTIFICATION_SHORT@”, “@TIMEOUT_NOTIFICATION_MIDDLE@”, “@TIMEOUT_NOTIFICATION_LONG@” are replaced with standard and translated templates.

2.4 Circular Progress Indicator

The circular progress indicator functions similarly to the progress bar. When given an id of “__timeout__”, GRUB updates the circular progress indicator’s value to indicate the time remaining.  For the circular progress indicator, there are two images used to render it: the *center* image, and the *tick* image.  The center image is rendered in the center of the component, while the tick image is used to render each mark along the circumference of the indicator.

2.5 Labels

Text labels can be placed on the boot screen.  The font, color, and horizontal alignment can be specified for labels.  If a label is given the id “__timeout__”, then the “text” property for that label is also updated with a message informing the user of the number of seconds remaining until automatic boot.  This is useful in case you want the text displayed somewhere else instead of directly on the progress bar.

2.6 Boot Menu

The boot menu where GRUB displays the menu entries from the “grub.cfg” file.  It is a list of items, where each item has a title and an optional icon.  The icon is selected based on the *classes* specified for the menu entry.  If there is a PNG “grub/themes/icons” directory, it will be displayed for items which have the class *myclass*.  The boot menu can be customized in several ways, such as the font and color used for the menu entry title, and by specifying styled boxes for the menu itself and for the selected item highlight.



I have started ( aka in 2009 as my own personal reference blog, and later sometime i have realized that my leanings might be helpful for other unixadmins if I manage my knowledge-base in more user friendly format. And the result is today's' You can connect me at -

1 Response

  1. October 6, 2015

    […] Mastering Grub – Part 2 – Grub Configurations […]

What is in your mind, about this post ? Leave a Reply

  Our next learning article is ready, subscribe it in your email

What is your Learning Goal for Next Six Months ? Talk to us