Skip to content

grub

Technical reference for the GRUB bootloader with emphasis on UEFI runtime behavior, kernel parameterization, boot-time hardening, disk encryption, logging control, and deterministic configuration for Linux systems.


Install grub:2 on Gentoo Linux

emerge --ask grub:2

Mount efivars if not mounted by default

mount -t efivarfs none /sys/firmware/efi/efivars

UEFI

Parameter Result
efi=runtime Forces EFI runtime services to remain active
efi=noruntime Disables EFI runtime services
efi=disable_efivars Disables efivarfs only
efi=disable Disables all EFI runtime services
noefi Completely ignores EFI (extreme)

Disable mounting /sys/firmware/efi/efivars at boot

GRUB_CMDLINE_LINUX="efi=disable_efivars"

You will find all uuids you need by blkid tool

blkid

uuids can be found by using ls command

ls -l /dev/disk/by-uuid | awk '{print $9 " -> " $11}'

uuids can also be found in /dev partition, find version

for u in /dev/disk/by-uuid/*; do echo "$(basename "$u") -> $(readlink -f "$u")"; done

Find uuids by using find in posix-friendly version

find /dev/disk/by-uuid -type l -printf '%f -> %l\n'

Extra: Find uuids with filesystem for each partition

for u in /dev/disk/by-uuid/*; do
  dev=$(readlink -f "$u")
  echo "$(basename "$u") -> $dev ($(lsblk -no FSTYPE "$dev"))"
done

Set uuid to the encrypted partition

GRUB_CMDLINE_LINUX="crypt_root=UUID=uuid_to_encrypted_partition"

Set uuid to the lvm partition

GRUB_CMDLINE_LINUX="real_root=UUID=uuid_to_lvm_drive"

Set uuid to swap partition

GRUB_CMDLINE_LINUX="resume=UUID=swap_uuid"

When set to 0 it will not ask for passphrase and look for key immediately

GRUB_CMDLINE_LINUX="key_timeout=0"

Where the usb key is stored on usb drive

GRUB_CMDLINE_LINUX="root_key=keyfiles/your_gpg.key.gpg"

UUID to usb-drive

GRUB_CMDLINE_LINUX="root_keydev=UUID=uuid_to_usb_drive"

Enable LVM support during early boot

GRUB_CMDLINE_LINUX="dolvm"

Logs

Name Meaning
0 KERN_EMERG System is unusable (panic-level)
1 KERN_ALERT Immediate action required
2 KERN_CRIT Critical conditions
3 KERN_ERR Errors
4 KERN_WARNING Warnings (default)
5 KERN_NOTICE Normal but significant
6 KERN_INFO Informational messages
7 KERN_DEBUG Debug-level messages

Set loglevel

GRUB_CMDLINE_LINUX="loglevel=3"

Runtime equivalents

cat /proc/sys/kernel/printk

Change loglevel temporary

dmesg -n 3

Misc

Disable most log messages

GRUB_CMDLINE_LINUX="quiet"

Enable splash

GRUB_CMDLINE_LINUX="splash"

Disable ipv6 from system

GRUB_CMDLINE_LINUX="ipv6.disable=1"

Install grub

grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Gentoo Linux"

Generate new grub.cfg file

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

Disable the annoying os_prober message when using grub-mkconfig

  • This is for single boot, for dual boot set the value to yes instead
$ echo ">=sys-boot/grub-2.14 mount" >> /etc/portage/package.use/grub
$ emerge --ask sys-boot/os-prober
GRUB_DISABLE_OS_PROBER=false

You might see another error but it can be ignored, it looks like:

!!! Warning: "os-prober will be executed to detect other bootable partitions. Its output will be used to detect bootable binaries on them and create new boot entries" when generating new grub-mkconfig file.

Themes

Set new theme for grub

  • Create mkdir -vp /boot/grub/themes/<theme_path>/theme.txt
GRUB_THEME="/boot/grub/themes/gentoo_glass/theme.txt"

Menu Colors

GRUB_COLOR_NORMAL="white/black"
GRUB_COLOR_HIGHLIGHT="white/green"

Hidden Menu

One of the unique features of GRUB is hiding/skipping the menu and showing it by holding Esc when needed. You can also adjust whether you want to see the timeout counter.

Hidden menu

GRUB_TIMEOUT=5
GRUB_TIMEOUT_STYLE='countdown'

Password protection of GRUB menu

If someone has physical access to your machine and is able to boot a live USB/disk (i.e., BIOS allows booting from an external disk), it is fairly trivial for one to modify GRUB configuration files to bypass this if /boot resides on an unencrypted partition. See GRUB#Encrypted /boot and Security#Data-at-rest encryption

Generate PBKDF2 hash

grub-mkpasswd-pbkdf2

Configure GRUB superuser

chmod 700 /etc/grub.d/40_custom
vim /etc/grub.d/40_custom
set superusers="grubadmin"
password_pbkdf2 grubadmin grub.pbkdf2.sha512.10000....

Where the hash is the string starting with grub.pbkdf2 generated by grub-mkpasswd-pbkdf2.

Regenerate grub.cfg

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

Resolution

Set resolution for grub at boot

GRUB_GFXMODE=1920x1080

Initrd

Load initrd at grub

GRUB_EARLY_INITRD="/intel-ucode.cpio"

CPU Perfomance

Set cpu governor speed

Governor Description
performance Locks CPU at the highest available frequency
powersave Locks CPU at the lowest available frequency
ondemand Quickly ramps up frequency under load, scales down when idle
conservative Like ondemand but scales frequency more gradually
schedutil Scheduler-driven, uses CFS load information (modern default on many systems)
userspace Frequency controlled manually from userspace

View available governors

cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors

Set governor level at boot

GRUB_EARLY_INITRD="cpufreq.default_governor=performance"

Examples

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

GRUB_DISTRIBUTOR="Gentoo"

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

GRUB_DEFAULT=0

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_TIMEOUT=10

List of space-separated early initrd images to be loaded from ‘/boot’. This is for loading things like CPU microcode, firmware, ACPI tables, crypto keys, and so on. These early images will be loaded in the order declared, and all will be loaded before the actual functional initrd image

GRUB_EARLY_INITRD="/intel-ucode.cpio"

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_TIMEOUT_STYLE=menu

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

GRUB_CMDLINE_LINUX_DEFAULT="crypt_root=UUID=6917c185-a82f-2332-q4a1-9a62902a7f19 real_root=UUID=7b0ac473-2323-1313-b7db-4ef667cfa5a1 rootfstype=ext4 dolvm loglevel=3 cpufreq.default_governor=performance"

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

#GRUB_TERMINAL=console

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_GFXMODE=1920x1080

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

#GRUB_GFXPAYLOAD_LINUX=

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

GRUB_THEME="/boot/grub/themes/gentoo_glass/theme.txt"

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. Image height and width will be restricted by an artificial limit of 16384

#GRUB_BACKGROUND="/boot/grub/mybackground.png"

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_LINUX_UUID=true

If grub-mkconfig cannot identify the root filesystem via its universally-unique indentifier (UUID), grub-mkconfig can use the UUID of the partition containing the filesystem to identify the root filesystem to the Linux kernel via a ‘root=PARTUUID=…’ kernel parameter. This is not as reliable as using the filesystem UUID, but is more reliable than using the Linux device names. When ‘GRUB_DISABLE_LINUX_PARTUUID’ is set to ‘false’, the Linux kernel version must be 2.6.37 (3.10 for systems using the MSDOS partition scheme) or newer. This option defaults to ‘true’. To enable the use of partition UUIDs, set this option to ‘false’

GRUB_DISABLE_LINUX_PARTUUID=false

Normally, grub-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 ‘true’, flat menu with all entries on top level will be generated instead. Changing this option will require changing existing values of ‘GRUB_DEFAULT’, ‘fallback’ (see fallback) and ‘default’ (see default) environment variables as well as saved default entry using grub-set-default and value used with grub-reboot

#GRUB_DISABLE_SUBMENU=y

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_INIT_TUNE="60 800 1"

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 recovery menu entry, before those listed in ‘GRUB_CMDLINE_LINUX’. The default is ‘single’

GRUB_DISABLE_RECOVERY=false

The grub-mkconfig has a feature to use the external os-prober program to discover other operating systems installed on the same machine and generate appropriate menu entries for them. It is disabled by default since automatic and silent execution of os-prober, and creating boot entries based on that data, is a potential attack vector. Set this option to ‘false’ to enable this feature in the grub-mkconfig command

GRUB_DISABLE_OS_PROBER=false