The boot loader GRUB 2 | Reference

Reference › System › The boot loader GRUB 2

Reference

Navigation←→

Applies to openSUSE Leap 15.3

12 The boot loader GRUB 2 #Edit source

Abstract#

This chapter describes how to configure GRUB 2, the boot loader used in openSUSE® Leap. A YaST module is available for configuring the most important settings. The boot procedure as a whole is outlined in Chapter 9, Introduction to the boot process. For details on Secure Boot support for UEFI machines, see Chapter 14, UEFI (Unified Extensible Firmware Interface).

12.1 Main differences between GRUB legacy and GRUB 2
12.2 Configuration file structure
12.3 Configuring the boot loader with YaST
12.4 Helpful GRUB 2 commands
12.5 More information

12.1 Main differences between GRUB legacy and GRUB 2 #Edit source

The configuration is stored in different files.
More file systems are supported (for example, Btrfs).
Can directly read files stored on LVM or RAID devices.
The user interface can be translated and altered with themes.
Includes a mechanism for loading modules to support additional features, such as file systems, etc.
Automatically searches for and generates boot entries for other kernels and operating systems, such as Windows.
Includes a minimal Bash-like console.

12.2 Configuration file structure #Edit source

The configuration of GRUB 2 is based on the following files:

/boot/grub2/grub.cfg: This file contains the configuration of the GRUB 2 menu items. It replaces menu.lst used in GRUB Legacy. grub.cfg should not be edited—it is automatically generated by the command grub2-mkconfig -o /boot/grub2/grub.cfg.
/boot/grub2/custom.cfg: This optional file is directly sourced by grub.cfg at boot time and can be used to add custom items to the boot menu. Starting with openSUSE Leap Leap 42.2 these entries will also be parsed when using grub-once.
/etc/default/grub: This file controls the user settings of GRUB 2 and usually includes additional environmental settings such as backgrounds and themes.
Scripts under /etc/grub.d/: The scripts in this directory are read during execution of the command grub2-mkconfig -o /boot/grub2/grub.cfg. Their instructions are integrated into the main configuration file /boot/grub/grub.cfg.
/etc/sysconfig/bootloader: This configuration file holds some basic settings like the boot loader type and whether to enable UEFI Secure Boot support.
/boot/grub2/x86_64-efi,: These configuration files contain architecture-specific options.

GRUB 2 can be controlled in various ways. Boot entries from an existing configuration can be selected from the graphical menu (splash screen). The configuration is loaded from the file /boot/grub2/grub.cfg which is compiled from other configuration files (see below). All GRUB 2 configuration files are considered system files, and you need root privileges to edit them.

Note: Activating configuration changes

After having manually edited GRUB 2 configuration files, you need to run grub2-mkconfig -o /boot/grub2/grub.cfg to activate the changes. However, this is not necessary when changing the configuration with YaST, because YaST will automatically run this command.

12.2.1 The file `/boot/grub2/grub.cfg` #Edit source

The graphical splash screen with the boot menu is based on the GRUB 2 configuration file /boot/grub2/grub.cfg, which contains information about all partitions or operating systems that can be booted by the menu.

Every time the system is booted, GRUB 2 loads the menu file directly from the file system. For this reason, GRUB 2 does not need to be re-installed after changes to the configuration file. grub.cfg is automatically rebuilt with kernel installations or removals.

grub.cfg is compiled from the file /etc/default/grub and scripts found in the /etc/grub.d/ directory when running the command grub2-mkconfig -o /boot/grub2/grub.cfg. Therefore you should never edit the file manually. Instead, edit the related source files or use the YaST Boot Loader module to modify the configuration as described in Section 12.3, “Configuring the boot loader with YaST”.

12.2.2 The file `/etc/default/grub` #Edit source

More general options of GRUB 2 belong here, such as the time the menu is displayed, or the default OS to boot. To list all available options, see the output of the following command:

> grep "export GRUB_DEFAULT" -A50 /usr/sbin/grub2-mkconfig | grep GRUB_

In addition to already defined variables, the user may introduce their own variables, and use them later in the scripts found in the /etc/grub.d directory.

After having edited /etc/default/grub, update the main configuration file with grub2-mkconfig -o /boot/grub2/grub.cfg.

Note: Scope

All options set in this file are general options that affect all boot entries. Specific options for Xen kernels or the Xen hypervisor can be set via the GRUB_*_XEN_* configuration options. See below for details.

GRUB_DEFAULT

Sets the boot menu entry that is booted by default. Its value can be a numeric value, the complete name of a menu entry, or “saved”.

GRUB_DEFAULT=2 boots the third (counted from zero) boot menu entry.

GRUB_DEFAULT="2>0" boots the first submenu entry of the third top-level menu entry.

GRUB_DEFAULT="Example boot menu entry" boots the menu entry with the title “Example boot menu entry”.

GRUB_DEFAULT=saved boots the entry specified by the grub2-once or grub2-set-default commands. While grub2-reboot sets the default boot entry for the next reboot only, grub2-set-default sets the default boot entry until changed. grub2-editenv list lists the next boot entry.

GRUB_HIDDEN_TIMEOUT

Waits the specified number of seconds for the user to press a key. During the period no menu is shown unless the user presses a key. If no key is pressed during the time specified, the control is passed to GRUB_TIMEOUT. GRUB_HIDDEN_TIMEOUT=0 first checks whether Shift is pressed and shows the boot menu if yes, otherwise immediately boots the default menu entry. This is the default when only one bootable OS is identified by GRUB 2.

GRUB_HIDDEN_TIMEOUT_QUIET

If false is specified, a countdown timer is displayed on a blank screen when the GRUB_HIDDEN_TIMEOUT feature is active.

GRUB_TIMEOUT

Time period in seconds the boot menu is displayed before automatically booting the default boot entry. If you press a key, the timeout is cancelled and GRUB 2 waits for you to make the selection manually. GRUB_TIMEOUT=-1 will cause the menu to be displayed until you select the boot entry manually.

GRUB_CMDLINE_LINUX

Entries on this line are added at the end of the boot entries for normal and recovery mode. Use it to add kernel parameters to the boot entry.

GRUB_CMDLINE_LINUX_DEFAULT

Same as GRUB_CMDLINE_LINUX but the entries are appended in the normal mode only.

GRUB_CMDLINE_LINUX_RECOVERY

Same as GRUB_CMDLINE_LINUX but the entries are appended in the recovery mode only.

GRUB_CMDLINE_LINUX_XEN_REPLACE

This entry will completely replace the GRUB_CMDLINE_LINUX parameters for all Xen boot entries.

GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT

Same as GRUB_CMDLINE_LINUX_XEN_REPLACE but it will only replace parameters ofGRUB_CMDLINE_LINUX_DEFAULT.

GRUB_CMDLINE_XEN

This entry specifies the kernel parameters for the Xen guest kernel only—the operation principle is the same as for GRUB_CMDLINE_LINUX.

GRUB_CMDLINE_XEN_DEFAULT

Same as GRUB_CMDLINE_XEN—the operation principle is the same as for GRUB_CMDLINE_LINUX_DEFAULT.

GRUB_TERMINAL

Enables and specifies an input/output terminal device. Can be console (PC BIOS and EFI consoles), serial (serial terminal), ofconsole (Open Firmware console), or the default gfxterm (graphics-mode output). It is also possible to enable more than one device by quoting the required options, for example GRUB_TERMINAL="console serial".

GRUB_GFXMODE

The resolution used for the gfxterm graphical terminal. Note that you can only use modes supported by your graphics card (VBE). The default is ‘auto’, which tries to select a preferred resolution. You can display the screen resolutions available to GRUB 2 by typing videoinfo in the GRUB 2 command line. The command line is accessed by typing C when the GRUB 2 boot menu screen is displayed.

You can also specify a color depth by appending it to the resolution setting, for example GRUB_GFXMODE=1280x1024x24.

GRUB_BACKGROUND

Set a background image for the gfxterm graphical terminal. The image must be a file readable by GRUB 2 at boot time, and it must end with the .png, .tga, .jpg, or .jpeg suffix. If necessary, the image will be scaled to fit the screen.

GRUB_DISABLE_OS_PROBER

If this option is set to true, automatic searching for other operating systems is disabled. Only the kernel images in /boot/ and the options from your own scripts in /etc/grub.d/ are detected.

SUSE_BTRFS_SNAPSHOT_BOOTING

If this option is set to true, GRUB 2 can boot directly into Snapper snapshots. For more information, see Section 3.3, “System rollback by booting from snapshots”.

For a complete list of options, see the GNU GRUB manual.

12.2.3 Scripts in `/etc/grub.d` #Edit source

The scripts in this directory are read during execution of the command grub2-mkconfig -o /boot/grub2/grub.cfg. Their instructions are incorporated into /boot/grub2/grub.cfg. The order of menu items in grub.cfg is determined by the order in which the files in this directory are run. Files with a leading numeral are executed first, beginning with the lowest number. 00_header is run before 10_linux, which would run before 40_custom. If files with alphabetic names are present, they are executed after the numerically-named files. Only executable files generate output to grub.cfg during execution of grub2-mkconfig. By default all files in the /etc/grub.d directory are executable.

Tip: Persistent custom content in `grub.cfg`

Because /boot/grub2/grub.cfg is recompiled each time grub2-mkconfig is run, any custom content is lost. If you want to insert your lines directly into /boot/grub2/grub.cfg without losing them after grub2-mkconfig is run, insert them between

### BEGIN /etc/grub.d/90_persistent ###

and

### END /etc/grub.d/90_persistent ###

The 90_persistent script ensures that such content will be preserved.

A list of the most important scripts follows:

00_header: Sets environmental variables such as system file locations, display settings, themes, and previously saved entries. It also imports preferences stored in the /etc/default/grub. Normally you do not need to make changes to this file.
10_linux: Identifies Linux kernels on the root device and creates relevant menu entries. This includes the associated recovery mode option if enabled. Only the latest kernel is displayed on the main menu page, with additional kernels included in a submenu.
30_os-prober: This script uses os-prober to search for Linux and other operating systems and places the results in the GRUB 2 menu. There are sections to identify specific other operating systems, such as Windows or macOS.
40_custom: This file provides a simple way to include custom boot entries into grub.cfg. Make sure that you do not change the exec tail -n +3 $0 part at the beginning.

The processing sequence is set by the preceding numbers with the lowest number being executed first. If scripts are preceded by the same number the alphabetical order of the complete name decides the order.

Tip: `/boot/grub2/custom.cfg`

If you create /boot/grub2/custom.cfg and fill it with content, it will be automatically included into /boot/grub2/grub.cfg just after 40_custom at boot time.

12.2.4 Mapping between BIOS drives and Linux devices #Edit source

In GRUB Legacy, the device.map configuration file was used to derive Linux device names from BIOS drive numbers. The mapping between BIOS drives and Linux devices cannot always be guessed correctly. For example, GRUB Legacy would get a wrong order if the boot sequence of IDE and SCSI drives is exchanged in the BIOS configuration.

GRUB 2 avoids this problem by using device ID strings (UUIDs) or file system labels when generating grub.cfg. GRUB 2 utilities create a temporary device map on the fly, which is usually sufficient, particularly in the case of single-disk systems.

However, if you need to override the GRUB 2's automatic device mapping mechanism, create your custom mapping file /boot/grub2/device.map. The following example changes the mapping to make DISK 3 the boot disk. Note that GRUB 2 partition numbers start with 1 and not with 0 as in GRUB Legacy.

(hd1)  /dev/disk-by-id/DISK3 ID
(hd2)  /dev/disk-by-id/DISK1 ID
(hd3)  /dev/disk-by-id/DISK2 ID

12.2.5 Editing menu entries during the boot procedure #Edit source

Being able to directly edit menu entries is useful when the system does not boot anymore because of a faulty configuration. It can also be used to test new settings without altering the system configuration.

In the graphical boot menu, select the entry you want to edit with the arrow keys.
Press E to open the text-based editor.
Use the arrow keys to move to the line you want to edit.
Figure 12.1: GRUB 2 boot editor #
Now you have two options:
1. Add space-separated parameters to the end of the line starting with linux or linuxefi to edit the kernel parameters. A complete list of parameters is available at https://en.opensuse.org/Linuxrc.
2. Or edit the general options to change for example the kernel version. The →| key suggests all possible completions.
Press F10 to boot the system with the changes you made or press Esc to discard your edits and return to the GRUB 2 menu.

Changes made this way only apply to the current boot process and are not saved permanently.

Important: Keyboard layout during the boot procedure

The US keyboard layout is the only one available when booting. See Book “Start-Up”, Chapter 4 “Troubleshooting”, Section 4.3 “Booting from installation media fails”, US keyboard layout.

Note: Boot loader on the installation media

The Boot Loader of the installation media on systems with a traditional BIOS is still GRUB Legacy. To add boot parameters, select an entry and start typing. Additions you make to the installation boot entry will be permanently saved in the installed system.

12.2.6 Setting a boot password #Edit source

Even before the operating system is booted, GRUB 2 enables access to file systems. Users without root permissions can access files in your Linux system to which they have no access after the system is booted. To block this kind of access or to prevent users from booting certain menu entries, set a boot password.

Important: Booting requires a password

If set, the boot password is required on every boot, which means the system does not boot automatically.

Proceed as follows to set a boot password. Alternatively use YaST (Protect Boot Loader with Password ).

Encrypt the password using grub2-mkpasswd-pbkdf2:

> sudo grub2-mkpasswd-pbkdf2
Password: ****
Reenter password: ****
PBKDF2 hash of your password is grub.pbkdf2.sha512.10000.9CA4611006FE96BC77A...

Paste the resulting string into the file /etc/grub.d/40_custom together with the set superusers command.
```
set superusers="root"
password_pbkdf2 root grub.pbkdf2.sha512.10000.9CA4611006FE96BC77A...
```
To import the changes into the main configuration file, run:
```
> sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```

After you reboot, you will be prompted for a user name and a password when trying to boot a menu entry. Enter root and the password you typed during the grub2-mkpasswd-pbkdf2 command. If the credentials are correct, the system will boot the selected boot entry.

For more information, see https://www.gnu.org/software/grub/manual/grub.html#Security.

12.2.7 Authorized access to boot menu entries #Edit source

You can configure GRUB 2 to allow access to boot menu entries depending on the level of authorization. You can configure multiple user accounts protected with passwords and assign them access to different menu entries. To configure authorization in GRUB 2, follow these steps:

Create and encrypt one password for each user account you want to use in GRUB 2. Use the grub2-mkpasswd-pbkdf2 command as described in Section 12.2.6, “Setting a boot password”.
Delete the content of the /etc/grub.d/10_linux file and save it. This prevents outputting the default GRUB 2 menu entries.

Edit the /boot/grub2/custom.cfg file and add custom menu entries manually. The following template is just an example, adjust it to better match your use case:

set superusers=admin
password admin ADMIN_PASSWORD
password maintainer MAINTAINER_PASSWORD

menuentry 'Operational mode' {
  insmod ext2
  set root=hd0,1
  echo 'Loading Linux ...'
  linux /boot/vmlinuz root=/dev/vda1 $GRUB_CMDLINE_LINUX_DEFAULT $GRUB_CMDLINE_LINUX mode=operation
  echo 'Loading Initrd ...'
  initrd /boot/initrd
}

menuentry 'Maintenance mode' --users maintainer {
  insmod ext2
  set root=hd0,1
  echo 'Loading Linux ...'
  linux /boot/vmlinuz root=/dev/vda1 $GRUB_CMDLINE_LINUX_DEFAULT $GRUB_CMDLINE_LINUX mode=maintenance
  echo 'Loading Initrd ...'
  initrd /boot/initrd
}

Import the changes into the main configuration file:
```
> sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```

In the above example:

The GRUB 2 menu has two entries, Operational mode and Maintenance mode.
If no user is specified, both boot menu entries are accessible, but no one can access GRUB 2 command line nor edit existing menu entries.
admin user can access GRUB 2 command line and edit existing menu entries.
maintenance user can select the recovery menu item.

12.3 Configuring the boot loader with YaST #Edit source

The easiest way to configure general options of the boot loader in your openSUSE Leap system is to use the YaST module. In the YaST Control Center, select System › Boot Loader. The module shows the current boot loader configuration of your system and allows you to make changes.

Use the Boot Code Options tab to view and change settings related to type, location and advanced loader settings. You can choose whether to use GRUB 2 in standard or EFI mode.

Figure 12.2: Boot code options #

Important: EFI systems require GRUB2-EFI

If you have an EFI system you can only install GRUB2-EFI, otherwise your system is no longer bootable.

Important: Reinstalling the boot loader

To reinstall the boot loader, make sure to change a setting in YaST and then change it back. For example, to reinstall GRUB2-EFI, select GRUB2 first and then immediately switch back to GRUB2-EFI.

Otherwise, the boot loader may only be partially reinstalled.

Note: Custom boot loader

To use a boot loader other than the ones listed, select Do Not Install Any Boot Loader. Read the documentation of your boot loader carefully before choosing this option.

12.3.1 Boot loader location and boot code options #Edit source

The default location of the boot loader depends on the partition setup and is either the Master Boot Record (MBR) or the boot sector of the / partition. To modify the location of the boot loader, follow these steps:

Procedure 12.1: Changing the boot loader location #

Select the Boot Code Options tab and then choose one of the following options for Boot Loader Location:
Boot from Master Boot Record
This installs the boot loader in the MBR of the disk containing the directory /boot. Usually this will be the disk mounted to /, but if /boot is mounted to a separate partition on a different disk, the MBR of that disk will be used.
Boot from Root Partition
This installs the boot loader in the boot sector of the / partition.
Custom Root Partition
Use this option to specify the location of the boot loader manually.
Click OK to apply the changes.

Figure 12.3: Code options #

The Boot Code Options tab includes the following additional options:

Set Active Flag in Partition Table for Boot Partition: Activates the partition that contains the /boot directory. For POWER systems it activates the PReP partition. Use this option on systems with old BIOS and/or legacy operating systems because they may fail to boot from a non-active partition. It is safe to leave this option active.
Write Generic Boot Code to MBR: If MBR contains a custom 'non-GRUB' code, this option replaces it with a generic, operating system independent code. If you deactivate this option, the system may become unbootable.
Enable Trusted Boot Support: Starts TrustedGRUB2, which supports trusted computing functionality (Trusted Platform Module (TPM)). For more information refer to https://github.com/Sirrix-AG/TrustedGRUB2.

The Protective MBR flag section includes the following options:

set: This is appropriate for traditional legacy BIOS booting.
remove: This is appropriate for UEFI booting.
do not change: This is usually the best choice if you have an already working system.

In most cases YaST defaults to the appropriate choice.

12.3.2 Adjusting the disk order #Edit source

If your computer has more than one hard disk, you can specify the boot sequence of the disks. The first disk in the list is where GRUB 2 will be installed in the case of booting from MBR. It is the disk where openSUSE Leap is installed by default. The rest of the list is a hint for GRUB 2's device mapper (see Section 12.2.4, “Mapping between BIOS drives and Linux devices”).

Warning: Unbootable system

The default value is usually valid for almost all deployments. If you change the boot order of disks wrongly, the system may become unbootable on the next reboot. For example, if the first disk in the list is not part of the BIOS boot order, and the other disks in the list have empty MBRs.

Procedure 12.2: Setting the disk order #

Open the Boot Code Options tab.
Click Edit Disk Boot Order.
If more than one disk is listed, select a disk and click Up or Down to reorder the displayed disks.
Click OK two times to save the changes.

12.3.3 Configuring advanced options #Edit source

Advanced boot parameters can be configured via the Boot Loader Options tab.

12.3.3.1 Boot Loader Options tab #Edit source

Figure 12.4: Boot loader options #

Boot Loader Time-Out: Change the value of Time-Out in Seconds by typing in a new value and clicking the appropriate arrow key with your mouse.
Probe Foreign OS: When selected, the boot loader searches for other systems like Windows or other Linux installations.
Hide Menu on Boot: Hides the boot menu and boots the default entry.
Adjusting the Default Boot Entry: Select the desired entry from the “Default Boot Section” list. Note that the “>” sign in the boot entry name delimits the boot section and its subsection.
Protect Boot Loader with Password: Protects the boot loader and the system with an additional password. For details on manual configuration, see Section 12.2.6, “Setting a boot password”. If this option is activated, the boot password is required on every boot, which means the system does not boot automatically. However, if you prefer the behavior of GRUB 1, additionally enable Protect Entry Modification Only. With this setting, anybody is allowed to select a boot entry and boot the system, whereas the password for the GRUB 2 root user is only required for modifying boot entries.

12.3.3.2 Kernel Parameters tab #Edit source

Figure 12.5: Kernel parameters #

Optional Kernel Command Line Parameter

Specify optional kernel parameters here to enable/disable system features, add drivers, etc.

CPU Mitigations

SUSE has released one or more kernel boot command line parameters for all software mitigations that have been deployed to prevent CPU side-channel attacks. Some of those may result in performance loss. Choose one the following options to strike a balance between security and performance, depending on your setting:

Auto. Enables all mitigations required for your CPU model, but does not protect against cross-CPU thread attacks. This setting may impact performance to some degree, depending on the workload.

Auto + No SMT. Provides the full set of available security mitigations. Enables all mitigations required for your CPU model. In addition, it disables Simultaneous Multithreading (SMT) to avoid side-channel attacks across multiple CPU threads. This setting may further impact performance, depending on the workload.

Off. Disables all mitigations. Side-channel attacks against your CPU are possible, depending on the CPU model. This setting has no impact on performance.

Manual. Does not set any mitigation level. Specify your CPU mitigations manually by using the kernel command line options.

Use Graphical Console

When checked, the boot menu appears on a graphical splash screen rather than in a text mode. The resolution of the boot screen is set automatically by default, but you can manually set it via Console resolution. The graphical theme definition file can be specified with the Console theme file chooser. Only change this if you want to apply your own, custom-made theme.

Use Serial Console

If your machine is controlled via a serial console, activate this option and specify which COM port to use at which speed. See info grub or http://www.gnu.org/software/grub/manual/grub.html#Serial-terminal

12.4 Helpful GRUB 2 commands #Edit source

grub2-mkconfig

Generates a new /boot/grub2/grub.cfg based on /etc/default/grub and the scripts from /etc/grub.d/.

Example 12.1: Usage of grub2-mkconfig #

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

Tip: Syntax check

Running grub2-mkconfig without any parameters prints the configuration to STDOUT where it can be reviewed. Use grub2-script-check after /boot/grub2/grub.cfg has been written to check its syntax.

Important: `grub2-mkconfig` cannot repair UEFI Secure Boot tables

If you are using UEFI Secure Boot and your system is not reaching GRUB 2 correctly anymore, you may need to additionally reinstall the Shim and regenerate the UEFI boot table. To do so, use:

# shim-install --config-file=/boot/grub2/grub.cfg

grub2-mkrescue

Creates a bootable rescue image of your installed GRUB 2 configuration.

Example 12.2: Usage of grub2-mkrescue #

grub2-mkrescue -o save_path/name.iso iso

grub2-script-check

Checks the given file for syntax errors.

Example 12.3: Usage of grub2-script-check #

grub2-script-check /boot/grub2/grub.cfg

grub2-once

Set the default boot entry for the next boot only. To get the list of available boot entries use the --list option.

Example 12.4: Usage of grub2-once #

grub2-once number_of_the_boot_entry

Tip: `grub2-once` help

Call the program without any option to get a full list of all possible options.

12.5 More information #Edit source

Extensive information about GRUB 2 is available at https://www.gnu.org/software/grub/. Also refer to the grub info page.

Print this page