Install & Config GRUB

CA Keys

To make use of CA Keys the command is:

						# grub-install --target=x86_64-efi --efi-directory=esp --bootloader-id=GRUB --modules="tpm" --disable-shim-lock
					

Shim-lock

Note: Before following this section you should make sure you have followed the instructions at Secure Boot#shim and have sbsigntools set-up and ready to receive keys.

When using Shim-lock, GRUB can only be successfully booted in Secure Boot mode if its EFI binary includes all of the modules necessary to read the filesystem containing the vmlinuz and initramfs images.

Since GRUB version 2.06.r261.g2f4430cc0, loading modules in Secure Boot Mode via insmod is no longer allowed, as this would violate the expectation to not sideload arbitrary code. If the GRUB modules are not embedded in the EFI binary, and GRUB tries to sideload/insmod them, GRUB will fail to boot with the message:

						error: prohibited by secure boot policy
					

Ubuntu, according to its official build script, embeds the following GRUB modules in its signed GRUB EFI binary grubx64.efi:

1. the "basic" modules, necessary for booting from a CD or from a simple-partitioned disk: all_video, boot, btrfs, cat, chain, configfile, echo, efifwsetup, efinet, ext2, fat, font, gettext, gfxmenu, gfxterm, gfxterm_background, gzio, halt, help, hfsplus, iso9660, jpeg, keystatus, loadenv, loopback, linux, ls, lsefi, lsefimmap, lsefisystab, lssal, memdisk, minicmd, normal, ntfs, part_apple, part_msdos, part_gpt, password_pbkdf2, png, probe, reboot, regexp, search, search_fs_uuid, search_fs_file, search_label, sleep, smbios, squash4, test, true, video, xfs, zfs, zfscrypt, zfsinfo
2. the "platform-specific" modules for x86_64-efi architecture, necessary for e.g.:
   • play: to play sounds during boot
   • cpuid: to the CPU at boot
   • tpm: to support Measured Boot / Trusted Platform Modules
3. the "advanced" modules, consisting of modules:
   • cryptodisk: to boot from plain-mode encrypted disks
   • gcry_algorithm: to support particular hashing and encryption algorithms
   • luks: to boot from LUKS-encrypted disks:
   • lvm: to boot from LVM logical volume disks
   • mdraid09, mdraid1x, raid5rec, raid6rec: to boot from RAID virtual disks

You must construct your list of GRUB modules in the form of a shell variable that we denote as GRUB_MODULES. You can use the latest Ubuntu script as a starting point, and trim away modules that are not necessary on your system. Omitting modules will make the boot process relatively faster, and save some space on the ESP partition.

You also need a Secure Boot Advanced Targeting (SBAT) file/section included in the EFI binary, to improve the security; if GRUB is launched from the UEFI shim loader. This SBAT file/section contains metadata about the GRUB binary (version, maintainer, developer, upstream URL) and makes it easier for shim to block certain GRUB versions from being loaded if they have security vulnerabilities^[1][2], as explained in the UEFI shim boot loader secure boot life-cycle improvements document from shim.

The first-stage UEFI boot loader shim will fail to launch grubx64.efi if the SBAT section from grubx64.efi is missing!

If GRUB is installed, a sample SBAT .csv file is provided under /usr/share/grub/sbat.csv.

Reinstall GRUB using the provided /usr/share/grub/sbat.csv file and all the needed GRUB_MODULES and sign it:

						# grub-install --target=x86_64-efi --efi-directory=esp --modules=${GRUB_MODULES} --sbat /usr/share/grub/sbat.csv
						# sbsign --key MOK.key --cert MOK.crt --output esp/EFI/GRUB/grubx64.efi esp/EFI/GRUB/grubx64.efi
						# cp esp/EFI/GRUB/grubx64.efi esp/EFI/BOOT/grubx64.efi
					

Reboot, select the key in MokManager, and Secure Boot should be working.

Using Secure Boot

After installation see Secure Boot#Implementing Secure Boot for instructions on enabling it.

If you are using the CA Keys method then key management, enrolment and file signing can be automated by using sbctl, see Secure Boot#Assisted process with sbctl for details.

Generate the main configuration file

After the installation, the main configuration file /boot/grub/grub.cfg needs to be generated. The generation process can be influenced by a variety of options in /etc/default/grub and scripts in /etc/grub.d/. For the list of options in /etc/default/grub and a concise description of each refer to GNU's documentation.

If you have not done additional configuration, the automatic generation will determine the root filesystem of the system to boot for the configuration file. For that to succeed it is important that the system is either booted or chrooted into.

• Note:
• • The default file path is /boot/grub/grub.cfg, not /boot/grub/i386-pc/grub.cfg.
  • If you are trying to run grub-mkconfig in a chroot or systemd-nspawn container, you might notice that it does not work: grub-probe: error: failed to get canonical path of /dev/sdaX. In this case, try using arch-chroot as described in the BBS post.

Use the grub-mkconfig tool to generate /boot/grub/grub.cfg:

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

By default the generation scripts automatically add menu entries for all installed Arch Linux kernels to the generated configuration.

• Tip:
• After installing or removing a kernel, you just need to re-run the above grub-mkconfig command.
• For tips on managing multiple GRUB entries, for example when using both linux and linux-lts kernels, see /Tips and tricks#Multiple entries.

To automatically add entries for other installed operating systems, see #Detecting other operating systems.

You can add additional custom menu entries by editing /etc/grub.d/40_custom and re-generating /boot/grub/grub.cfg. Or you can create /boot/grub/custom.cfg and add them there. Changes to /boot/grub/custom.cfg do not require re-running grub-mkconfig, since /etc/grub.d/41_custom adds the necessary source statement to the generated configuration file.

Tip: /etc/grub.d/40_custom can be used as a template to create /etc/grub.d/nn_custom, where nn defines the precedence, indicating the order the script is executed. The order scripts are executed determine the placement in the GRUB boot menu. nn should be greater than 06 to ensure necessary scripts are executed first.

See #Boot menu entry examples for custom menu entry examples.

Detecting other operating systems

To have grub-mkconfig search for other installed systems and automatically add them to the menu, install the os-prober package and mount the partitions from which the other systems boot. Then re-run grub-mkconfig. If you get the following output: Warning: os-prober will not be executed to detect other bootable partitions then edit /etc/default/grub and add/uncomment:

						GRUB_DISABLE_OS_PROBER=false
					

Then try again.

• Note:
• • The exact mount point does not matter, os-prober reads the mtab to identify places to search for bootable entries.
  • Remember to mount the partitions each time you run grub-mkconfig in order to include the other operating systems every time.
  • os-prober might not work properly when run in a chroot. Try again after rebooting into the system if you experience this.

Tip: You might also want GRUB to remember the last chosen boot entry, see /Tips and tricks#Recall previous entry.

• Windows:
• • For Windows installed in UEFI mode, make sure the EFI system partition containing the Windows Boot Manager (bootmgfw.efi) is mounted. Run os-prober as root to detect and generate an entry for it.
  • For Windows installed in BIOS mode, mount the Windows system partition (its file system label should be System Reserved or SYSTEM). Run os-prober as root to detect and generate an entry for it.

• Note:
• • os-prober might try to grub-mount a partition to probe whether the requisite .efi file exists. You need to install fuse3 to make grub-mount work properly. Otherwise, you may fail to detect a Windows system.
  • NTFS partitions may not always be detected when mounted with the default Linux drivers. If GRUB is not detecting it, try installing NTFS-3G and remounting.

Additional arguments

To pass custom additional arguments to the Linux image, you can set the GRUB_CMDLINE_LINUX + GRUB_CMDLINE_LINUX_DEFAULT variables in /etc/default/grub. The two are appended to each other and passed to kernel when generating regular boot entries. For the recovery boot entry, only GRUB_CMDLINE_LINUX is used in the generation.

It is not necessary to use both, but can be useful. For example, you could use GRUB_CMDLINE_LINUX_DEFAULT="resume=UUID=uuid-of-swap-partition quiet" where uuid-of-swap-partition is the UUID of your swap partition to enable resume after hibernation. This would generate a recovery boot entry without the resume and without quiet suppressing kernel messages during a boot from that menu entry. Though, the other (regular) menu entries would have them as options.

By default grub-mkconfig determines the UUID of the root filesystem for the configuration. To disable this, uncomment GRUB_DISABLE_LINUX_UUID=true.

For generating the GRUB recovery entry you have to ensure that GRUB_DISABLE_RECOVERY is not set to true in /etc/default/grub.

See Kernel parameters for more info.

Setting the top-level menu entry

By default, grub-mkconfig sorts the included kernels using sort -V and uses the first kernel in that list as the top-level entry. This means that, for example, since /boot/vmlinuz-linux-lts is sorted before /boot/vmlinuz-linux, if you have both linux-lts and linux installed, the LTS kernel will be the top-level menu entry, which may not be desirable. This can be overridden by specifying GRUB_TOP_LEVEL="path_to_kernel" in /etc/default/grub. For example, to make the regular kernel be the top-level menu entry, you can use GRUB_TOP_LEVEL="/boot/vmlinuz-linux".

LVM

Notes: grub-mkconfig is capable of detecting that it needs the lvm module, specifying it in GRUB_PRELOAD_MODULES is not required. Move warning to #Installation & #Installation_2 or create a Known issues section and document it there. (Discuss in Talk:GRUB.

Warning: GRUB does not support thin-provisioned logical volumes.

If you use LVM for your /boot or / root partition, make sure that the lvm module is preloaded:

						/etc/default/grub
					

						GRUB_PRELOAD_MODULES="... lvm"
					

RAID

Notes: grub-mkconfig is capable of detecting that it needs the mdraid09 and/or mdraid1x modules, specifying them in GRUB_PRELOAD_MODULES is not required. Summarize the double grub-install in a note and move it to #Installation; move set root stuff to #Custom grub.cfg. (Discuss in Talk:GRUB.

GRUB provides convenient handling of RAID volumes. You need to load GRUB modules mdraid09 or mdraid1x to allow you to address the volume natively:

						/etc/default/grub
					

						GRUB_PRELOAD_MODULES="... mdraid09 mdraid1x"
					

For example, /dev/md0 becomes:

						set root=(md/0)
					

whereas a partitioned RAID volume (e.g. /dev/md0p1) becomes:

						set root=(md/0,1)
					

To install grub when using RAID1 as the /boot partition (or using /boot housed on a RAID1 root partition), on BIOS systems, simply run grub-install on both of the drives, such as:

						# grub-install --target=i386-pc --debug /dev/sda
						# grub-install --target=i386-pc --debug /dev/sdb
					

Where the RAID 1 array housing /boot is housed on /dev/sda and /dev/sdb.

Note: GRUB supports booting from Btrfs RAID 0/1/10, but not RAID 5/6. You may use mdadm for RAID 5/6, which is supported by GRUB.

Encrypted /boot

GRUB also has special support for booting with an encrypted /boot. This is done by unlocking a LUKS blockdevice in order to read its configuration and load any initramfs and kernel from it. This option tries to solve the issue of having an unencrypted boot partition.

Tip: /boot is not required to be kept in a separate partition; it may also stay under the system's root / directory tree.

Warning: GRUB 2.12rc1 has limited support for LUKS2. See the #LUKS2 section below for details.

To enable this feature encrypt the partition with /boot residing on it using LUKS as normal. Then add the following option to /etc/default/grub:

						/etc/default/grub
					

						GRUB_ENABLE_CRYPTODISK=y
					

This option is used by grub-install to generate the grub core.img.

Make sure to install grub after modifying this option or encrypting the partition.

Without further changes you will be prompted twice for a passphrase: the first for GRUB to unlock the /boot mount point in early boot, the second to unlock the root filesystem itself as implemented by the initramfs. You can use a keyfile to avoid this.

• Warning:
• • If you want to generate the main configuration file, make sure that /boot is mounted.
  • In order to perform system updates involving the /boot mount point, ensure that the encrypted /boot is unlocked and mounted before performing an update. With a separate /boot partition, this may be accomplished automatically on boot by using crypttab with a keyfile.

• Note:
• • If you use a special keymap, a default GRUB installation will not know it. This is relevant for how to enter the passphrase to unlock the LUKS blockdevice. See Tips_and_tricks#Manual configuration of core image for early boot.
  • If you experience issues getting the prompt for a password to display (errors regarding cryptouuid, cryptodisk, or "device not found"), try reinstalling GRUB and appending --modules="part_gpt part_msdos" to the end of your grub-install command.

Tip: You can use pacman hooks to automount your /boot when upgrades need to access related files.

LoaderDevicePartUUID

For GRUB to set the LoaderDevicePartUUID UEFI variable required by systemd-gpt-auto-generator(8) for GPT partition automounting, load the bli module in grub.cfg:

						if [ "$grub_platform" = "efi" ]; then
						  insmod bli
						fi
					

Boot menu entry examples

Tip: These boot entries can also be used when using a /boot/grub/grub.cfg generated by grub-mkconfig. Add them to /etc/grub.d/40_custom and re-generate the main configuration file or add them to /boot/grub/custom.cfg.

For tips on managing multiple GRUB entries, for example when using both linux and linux-lts kernels, see /Tips and tricks#Multiple entries.

For Archiso and Archboot boot menu entries see Multiboot USB drive#Boot entries.

								menuentry "System shutdown" {
								  echo "System shutting down..."
								  halt
								}
							

								menuentry "System restart" {
								  echo "System rebooting..."
								  reboot
								}
							

								if [ ${grub_platform} == "efi" ]; then
								  menuentry 'UEFI Firmware Settings' --id 'uefi-firmware' {
								    fwsetup
								  }
								fi
							

							if [ ${grub_platform} == "efi" ]; then
							  place UEFI-only menu entries here
							fi
						

								menuentry "UEFI Shell" {
								  insmod fat
								  insmod chain
								  search --no-floppy --set=root --file /shellx64.efi
								  chainloader /shellx64.efi
								}
							

								menuentry "gdisk" {
								  insmod fat
								  insmod chain
								  search --no-floppy --set=root --file /EFI/tools/gdisk_x64.efi
								  chainloader /EFI/tools/gdisk_x64.efi
								}
							

								menuentry "Arch Linux" {
								  insmod fat
								  insmod chain
								  search --no-floppy --set=root --fs-uuid FILESYSTEM_UUID
								  chainloader /EFI/Linux/arch-linux.efi
								}
							

									menuentry "Other Linux" {
									  set root=(hd0,2)
									  linux /boot/vmlinuz (add other options here as required)
									  initrd /boot/initrd.img (if the other kernel uses/needs one)
									}
								

									menuentry "Other Linux" {
									  # assuming that UUID is 763A-9CB6
									  search --no-floppy --set=root --fs-uuid 763A-9CB6
									
									  # search by label OTHER_LINUX (make sure that partition label is unambiguous)
									  #search --no-floppy --set=root --label OTHER_LINUX
									
									  linux /boot/vmlinuz (add other options here as required, for example: root=UUID=763A-9CB6)
									  initrd /boot/initrd.img (if the other kernel uses/needs one)
									}
								

									menuentry "configfile hd0,gpt4"  {
									  insmod part_gpt
									  insmod btrfs
									  insmod ext2
									  set root='hd0,gpt4'
									  configfile /boot/grub/grub.cfg
									}
								

									if [ "${grub_platform}" == "efi" ]; then
									  menuentry "Microsoft Windows Vista/7/8/8.1 UEFI/GPT" {
									    insmod part_gpt
									    insmod fat
									    insmod chain
									    search --no-floppy --fs-uuid --set=root $hints_string $fs_uuid
									    chainloader /EFI/Microsoft/Boot/bootmgfw.efi
									  }
									fi
								

# grub-probe --target=fs_uuid esp/EFI/Microsoft/Boot/bootmgfw.efi
								

									1ce5-7f28
								

# grub-probe --target=hints_string esp/EFI/Microsoft/Boot/bootmgfw.efi
								

									--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1
								

									if [ "${grub_platform}" == "pc" ]; then
									  menuentry "Microsoft Windows Vista/7/8/8.1/10 BIOS/MBR" {
									    insmod part_msdos
									    insmod ntfs
									    insmod ntldr
									    search --no-floppy --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 XXXX-XXXX
									    ntldr /bootmgr
									  }
									fi
								

									if [ "${grub_platform}" == "pc" ]; then
									  menuentry "Microsoft Windows XP" {
									    insmod part_msdos
									    insmod ntfs
									    insmod ntldr
									    search --no-floppy --fs-uuid --set=root --hint-bios=hd0,msdos1 --hint-efi=hd0,msdos1 --hint-baremetal=ahci0,msdos1 XXXX-XXXX
									    ntldr /ntldr
									  }
									fi
								

									X:\> bootrec.exe /fixboot
									X:\> bootrec.exe /RebuildBcd
								

								menuentry "Arch Linux, session texte" {
								  search --label --set=root archroot
								  linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro
								  initrd /boot/initramfs-linux.img
								}