Skip to main content
Library homepage
Engineering LibreTexts

07-B.6: GRUB2 - Configuration

  • Page ID
  • \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    The grub.cfg File

    The grub.cfg file is the GRUB configuration file. It is generated by the grub2-mkconfig program using a set of primary configuration files and the grub default file as a source for user configuration specifications. The /boot/grub2/grub.cfg file is first generated during Linux installation and regenerated when a new kernel is installed.

    The grub.cfg file contains Bash-like code and a list of installed kernels in an array ordered by sequence of installation. For example, if you have four installed kernels, the most recent kernel will be at index 0, the previous kernel will be at index 1, and the oldest kernel will be index 3. If you have access to a grub.cfg file you should look at it to get a feel for what one looks like. The grub.cfg file is just too large to be included in this article.

    The video discusses how to configure GRUB. It is important you understand how to use GRUB, and the ramifications of not understanding what you are doing.

    GRUB defaults file

    Configuration of the original GRUB was fairly simple and straightforward. I would just modify /boot/grub/grub.conf and be good to go. I could still modify GRUB2 by changing /boot/grub2/grub.cfg, but the new version is considerably more complex than the original GRUB. In addition, grub.cfg may be overwritten when a new kernel is installed, so any changes may disappear. However, the GRUB Manual does discuss direct creation and modification of /boot/grub2/grub.cfg.

    Changing the configuration for GRUB2 is fairly easy once you actually figure out how to do it. I only discovered this while researching GRUB2 for a previous article. The secret formula is in the /etc/default directory, with a file called, naturally enough, grub, which is then used in concert with a simple terminal command. The /etc/default directory contains configuration files for a few programs such as Google Chrome, useradd, and grub.

    The /etc/default/grub file is very simple. The grub defaults file has a number of valid key/value pairs listed already. You can simply change the values of existing keys or add other keys that are not already in the file. Listing 1, below, shows an unmodified /etc/default/grub file.

    GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g'
    GRUB_CMDLINE_LINUX=" rhgb quiet"

    Section 5.1 of the GRUB Manual contains information about all of the possible keys that can be included in the grub file. I have never needed to do anything other than modifying the values of some of the keys that are already in the grub default file. Let's look at what each of these keys means as well as some that don't appear in the grub default file.

    • GRUB_TIMEOUT The value of this key determines the length of time that the GRUB selection menu is displayed. GRUB offers the capability to keep multiple kernels installed simultaneously and choose between them at boot time using the GRUB menu. The default value for this key is five seconds, but I usually change that to 10 seconds to allow more time to view the choices and make a selection.
    • GRUB_DISTRIBUTOR This key defines a sed expression that extracts the distribution release number from the /etc/system-release file. This information is used to generate the text names for each kernel release that appears in the GRUB menu, such as "Fedora." Due to variations in the structure of the data in the system-release file between distributions, this sed expression may be different on your system.
    • GRUB_DEFAULT Determines which kernel is booted by default. That is, the "saved" kernel which is the most recent kernel. Other options here are a number which represents the index of the list of kernels in grub.cfg. Using an index such as 3, however, to load the fourth kernel in the list will always load the fourth kernel in the list even after a new kernel is installed. So using an index will load a different kernel after a new kernel is installed. The only way to ensure that a specific kernel release is booted is to set the value of GRUB_DEFAULT to the name of the desired kernel, like 4.8.13-300.fc25.x86_64.
    • GRUB_SAVEDEFAULT Normally, this option is not specified in the grub defaults file. Normal operation when a different kernel is selected for boot; that kernel is booted only that one time. The default kernel is not changed. When set to "true" and used with GRUB_DEFAULT=saved this option saves a different kernel as the default. This happens when a different kernel is selected for boot.
    • GRUB_DISABLE_SUBMENU Some people may wish to create a hierarchical menu structure of kernels for the GRUB menu screen. This key, along with some additional configuration of the kernel stanzas in grub.cfg allows creating such a hierarchy. For example, the one might have the main menu with "production" and "test" sub-menus where each sub-menu would contain the appropriate kernels. Setting this to "false" would enable the use of sub-menus.
    • GRUB_TERMINAL_OUTPUT In some environments it may be desirable or necessary to redirect output to a different display console or terminal. The default is to send output to the default terminal, usually the "console" which equates to the standard display on an Intel class PC. Another useful option is to specify "serial" in a data center or lab environment in which serial terminals or Integrated Lights Out (ILO) terminal connections are in use.
    • GRUB_TERMINAL_INPUT As with GRUB_TERMINAL_OUTPUT, it may be desirable or necessary to redirect input from a serial terminal or ILO device rather than the standard keyboard input.
    • GRUB_CMDLINE_LINUX This key contains the command line arguments that will be passed to the kernel at boot time. Note that these arguments will be added to the kernel line of grub.cfg for all installed kernels. This means that all installed kernels will have the same arguments when booted. I usually remove the "rhgb" and "quiet" arguments so that I can see all of the very informative messages output by the kernel and systemd during the boot and startup.
    • GRUB_DISABLE_RECOVERY When the value of this key is set to "false," a recovery entry is created in the GRUB menu for every installed kernel. When set to "true" no recovery entries are created. Regardless of this setting, the last kernel entry is always a "rescue" option. However, I encountered a problem with the rescue option, which I'll talk more about below.

    The /etc/grub.d Directory

    The main set of configuration files for grub.cfg is located in the /etc/grub.d directory. Each of the files in that directory contains GRUB code that is collected into the final grub.cfg file. The numbering scheme used in the names of these configuration files is designed to provide ordering so that the final grub.cfg file is assembled into the correct sequence. Each of these files has a comment to denote the beginning and end of the section, and those comments are also part of the final grub.cfg file so that it is possible to see from which file each section is generated. The delimiting comments look like this:

    ### BEGIN /etc/grub.d/10_linux ###
    ### END /etc/grub.d/10_linux ###

    These files should not be modified unless you are a GRUB expert and understand what the changes will do. Even then you should always keep a backup copy of the original, working grub.cfg file. The specific files, 40_custom and 41_custom are intended to be used to generate user modifications to the GRUB configuration. You should still be aware of the consequences of any changes you make to these files and maintain a backup of the original grub.cfg file.

    You can also add your own files to the /etc/grub.d directory. One reason for doing that might be to add a menu line for a non-Linux operating system. Just be sure to follow the naming convention to ensure that the additional menu item is added either immediately before or after the 10_linux entry in the configuration file.

    You can also add your own files to the /etc/grub.d directory. One reason for doing that might be to add a menu line for a non-Linux operating system. Just be sure to follow the naming convention to ensure that the additional menu item is added either immediately before or after the 10_linux entry in the configuration file.

    How to Customize GRUB2 Boot Menu

    GRUB 2 constructs the menu via a series of scripts, with each script building a portion of the menu. These scripts include /etc/grub.d/00_header and /etc/grub.d/05_header. The GRUB 2 menu configuration file (grub.cfg) includes section remarks showing which script is responsible for creating the section. The /etc/default/grub file contains most of the user-defined variables such as display time, menu resolution and default menu entry. Most custom menu users will want to allow these components to continue to operate normally.

    A sample custom menu called 40_custom is provided in the /etc/grub.d/ folder. This file can be used or copied. The current 40_custom file contains only lines which are not actually imported into grub.cfg. In general, users should honor the comments and leave these lines alone, adding custom entries below the existing lines. The 40_customer file looks something like:

    exec tail -n +3 $0
    # This file provides an easy way to add custom menu entries.  Simply type the
    # menu entries you want to add after this comment.  Be careful not to change
    # the 'exec tail' line above.

    One common customization is the addition of a password to protect the GRUB2 menu. The password can be generated by using the grub2-mkpasswd-pbkdf2 command. Enter this command, type in the desired password twice as requested and it generates the password.

    pbmac@pbmac-server $ sudo grub-mkpasswd-pbkdf2
    Enter password: 
    Reenter password: 
    PBKDF2 hash of your password is grub.pbkdf2.sha512.10000.E71841FEC7692B19F7819BEDD0ED9B28C690C97375A384D80782

    This password can then be entered into the 40_customer file. You need to enter a valid user id in the "set superuser=" line, then enter the "password_pbkdf2," followed by the userid then paste the generated password.

    exec tail -n +3 $0
    # This file provides an easy way to add custom menu entries.  Simply type the
    # menu entries you want to add after this comment.  Be careful not to change
    # the 'exec tail' line above.
    set superuse="pbmac"
    password_pbkdf2 pbmac grub.pbkdf2.sha512.10000.E71841FEC7692B19F7819BEDD0ED9B28C690C97375A384D80782

    The grub-mkconfig Command

    Depending on the distribution of Linux you are running the command might be grub-mkconfig, and on other distros it is grub2-mkconfig. After completing the desired configuration it is necessary to generate the /boot/grub2/grub.cfg file.

    This is a simple command - with a single option -o, to output the results to the specified file.

    This is accomplished with the following command.

    grub-mkconfig -o /boot/grub2/grub.cfg

    This command takes the configuration files located in /etc/grub.d in sequence to build the grub.cfg file, and uses the contents of the grub defaults file to modify the output to achieve the final desired configuration. The grub-mkconfig command attempts to locate all of the installed kernels and creates an entry for each in the 10_Linux section of the grub.cfg file. It also creates a "rescue" entry to provide a method for recovering from significant problems that prevent Linux from booting.

    It is strongly recommended that you do not edit the grub.cfg file manually because any direct modifications to the file will be overwritten the next time a new kernel is installed or grub-mkconfig is run manually.

    Adapted from
    "An introduction to GRUB2 configuration for your Linux machine" by David Both, is licensed under CC BY-SA 4.0
    "Grub2/Passwords" by Eric Heintzmann, CommunityHelpWiki is licensed under CC BY-SA 3.0
    "Grub2/Setup" by sudodus, CommunityHelpWiki is licensed under CC BY-SA 3.0
    "Grub2/CustomMenus" by damage3025, CommunityHelpWiki is licensed under CC BY-SA 3.0

    07-B.6: GRUB2 - Configuration is shared under a CC BY-NC license and was authored, remixed, and/or curated by LibreTexts.

    • Was this article helpful?