Optional: Creating Backup of Existing GRUB Legacy Installation
Playing with your bootloader always brings the danger of leaving your system in an
unbootable state. Fortunately, no data is lost in most cases and recovery is not
hard, but we recommend you to have a bootable CD, DVD or a USB flash disk with
Linux around (Gentoo
LiveDVD or System Rescue CD
will do) and to backup your current bootloader setup. If your current
bootloader is GRUB Legacy, the following code sample will help you backing it up.
# # backup grub modules and configuration
# cp -a /boot/grub /path/to/backup/
# # backup the MBR and GRUB stage 1.5
# dd if=/dev/sda of=/path/to/backup/first-sectors count=63
Replace /dev/sda with the device node of the disk you boot from (this is
usually the whole disk like sda, not a partition like sda1) and
/path/to/backup with the path to your favourite backup medium.
When something goes wrong, you can restore the previous grub installation by
booting some Linux live media and issuing following commands.
# # move old grub files out of the way
# mv /boot/grub /boot/grub.nonfunctional
# # copy grub back to /boot
# cp -a /path/to/backup/grub /boot/
# # replace MBR and next 62 sectors of sda with backed up copy (DANGEROUS!)
# dd if=/path/to/backup/first-sectors of=/dev/sda count=63
Replace /dev/sda with the device node of the disk you boot from and
/path/to/backup with the path to the place where you've stored your backup.
Writing directly to disk sectors (even those that are outside of partitions
in typical setup) is risky operation and will make your data inaccessible
if you changed your partition layout between backup and restore. Other slower
and safer option would be chrooting into your Gentoo installation and
re-installing bootloader - you can use Gentoo
Handbook for that task.
Variant B: Installing GRUB 2 on Hardware That Supports EFI
Some newer PCs (and all Intel Macs) come with
EFI
(UEFI to be correct) as a replacement for legacy
and ageing BIOS firmware. EFI usually can emulate BIOS environment for OS, but
that also hides some unique features of EFI such as faster boot times, support
for GPT partition tables, etc. EFI firmware comes in two flavours - 32bit and
64bit and unless you have early Intel-based Mac with 32bit processor, your
firmware will be likely 64bit. Please note that unlike in user-space, 64bit
EFI firmware cannot run 32bit EFI bootloader. This section will guide you
through installing GRUB 2 on such EFI-capable boards; it assumes that your
firmware adheres to UEFI 2.0 standard or newer (virtually every PC with EFI
support; Intel Macs do not entirely conform to the specification and may need
special treatment in some places)
First thing you need is EFI-enabled Linux kernel with
CONFIG_EFI and CONFIG_EFI_PARTITION options enabled,
CONFIG_FB_EFI and CONFIG_EFI_VARS being optional but recommended.
Some platforms (namely many boards designed for Intel Sandy Bridge
processor generation) have
buggy EFI implementations and require at least kernel versions 2.6.39.1
or 3.0 in order to successfully boot.
One big difference between BIOS and EFI is that EFI is able to read partition
tables (both MBR and GPT formats should be supported) and to read from a specially
labelled FAT32 partition called EFI System Partition. During bootup, EFI
firmware can execute EFI applications stored in files in EFI System
Partition. One special EFI application is a bootloader. You may use the EFI
System Partition as your /boot partition if you don't mind limitations
of the FAT32 filesystem such as no support for symlinks and per-file owner and
permissions. The rest of this section assumes that you use /boot for
mounting EFI System Partition.
If you don't already have an EFI System Partition, let's create one. The procedure is
different for GPT and MBR-formatted disks. The partition does not need to be the first
one on the disk as in our examples. In case it is GPT-partitioned you'll need one
of the gdisk (CLI, sys-apps/gptfdisk), parted (CLI,
sys-block/parted) or gparted (GUI, sys-block/gparted) partitioning
tools; fdisk, cfdisk and sfdisk do not currently support
GPT. In the GPT case, create a partition at least 100 MiB in size with
boot flag (shown by (g)parted) or EF00 Code (shown by gdisk).
Replace /dev/sda with the disk you want to have the EFI System Partition on and
/dev/sda1 with the partition designated for it in all following samples.
# gdisk -l /dev/sda
(...)
Number Start (sector) End (sector) Size Code Name
1 34 411647 201.0 MiB EF00
# parted -l
(...)
Number Start End Size File system Name Flags
1 17.4kB 211MB 211MB fat32 boot # the File system field may be empty
In case the disk partition scheme is MBR (MS-DOS), the EFI System Partition should
have type EF. Create or re-type it, it should be at least 100 MiB large here, too.
# fdisk -l /dev/sda
(...)
Device Boot Start End Blocks Id System
/dev/sda1 2048 206847 102400 ef EFI (FAT-12/16/32)
Next, create a FAT32 filesystem on it if you already haven't done so. From now on,
procedure is the same for both GPT and MBR-formatted disks. Program
mkdosfs is from package sys-fs/dosfstools.
# mkdosfs -F 32 -n efi-boot /dev/sda1
mkdosfs 3.0.9 (31 Jan 2010)
This command erases everything that was previously on /dev/sda1.
The -F 32 option tells mkdosfs to create FAT32 filesystem and -n
efi-boot option tells mkdosfs to set the partition label to efi-boot.
You may use arbitrary string up to 11 characters long as label or you may not
use it at all.
Next, you should add (or edit) an entry for the /boot partition into fstab and
mount it:
# cat /etc/fstab | grep efi-boot
LABEL=efi-boot /boot vfat defaults 0 2
# mount /boot
Next, you should copy GRUB 2 modules into /boot where they can be found by
GRUB 2 during system boot:
# mkdir -p /boot/grub2
# cp /lib/grub2/x86_64-efi/* /boot/grub2/
The most crucial step is creating the GRUB 2 image (EFI application). This is
accomplished using the grub2-mkimage command:
# grub2-mkimage -p /grub2 -o /boot/grub2/grub.efi -O x86_64-efi part_msdos part_gpt fat
| grub2-mkimage options |
recommended value |
notes |
| -p |
where should GRUB 2 look for its modules and config?
/grub2
relative to the root of the
partition where GRUB 2 EFI application is executed from
| -o |
where to store created image?
/boot/grub2/grub.efi
| -O |
platform to create image for
x86_64-efi
replace with i386-efi on 32-bit systems (old Intel Macs)
| <rest> |
modules from /lib/grub2/[platform] to statically link in
part_msdos part_gpt fat
you only need to specify modules that are needed to be able to load other
modules from filesystem. You may drop part_msdos or part_gpt if
you don't use such partitions. You may add normal for a decent GRUB 2
shell available even in cases GRUB 2 cannot load other modules
When the GRUB 2 image (EFI application) is made, you have to tell your firmware
to execute it upon boot. There are two ways to achieve this. If there is
already a default bootloader on your EFI System Partition that you don't want
to overwrite, you have to use the second. Otherwise you can use the first and
we encourage you to do so, since it is simpler.
# mkdir -p /boot/EFI/BOOT
# cp /boot/grub2/grub.efi /boot/EFI/BOOT/BOOTX64.EFI
EFI 2 specification says that the default bootloader location is [EFI System
Partition]\EFI\BOOT\BOOTx64.EFI for x86_64 hardware. (and
...\BOOTIA32.EFI on 32bit systems) While FAT32 filesystems should be
case-insensitive, it is recommended to use ALL-CAPS filenames in default
bootloader path in order to be compatible with all vfat mount options.
# efibootmgr TODO TODO TODO
Executing efibootmgr on Macs is known to brick (destroy) your firmware!
Various sources report that the bless command should be used instead.
Last, you should create a GRUB 2 environment file (where GRUB 2 stores persistent
variables such as the number of the last booted item) as it is not created
automatically:
# grub2-editenv - create
When you update GRUB 2, be sure to execute all commands that are marked as
such. Failure to do so would result in you using (parts of) the previously installed GRUB
version.
The last step is actually installing Linux kernel images into /boot, then you
can easily proceed with generating the configuration.
Configuring GRUB 2
Gentoo installs all grub commands renamed to grub2. So if you read any other guide you
should replace all grub mentions with grub2 (grub-mkconfig -> grub2-mkconfig).
Compared to GRUB Legacy, GRUB 2 uses automatic generation to generate
all the required entries for you to boot. This is handled by grub2-mkconfig
command that probes your system for all the required data. Cooperating with
sys-boot/os-prober, it detects even other OSes on all disks.
If you want to configure GRUB 2 from a chrooted environment (e.g. from the
Gentoo LiveDVD) and you need os-prober functionality, you have to mount the sysfs
from the live system:
# mount --rbind /sys /path/to/chroot/sys
If you updated from GRUB Legacy then your /boot/grub/menu.lst
was converted to /boot/grub2/grub.cfg to ensure that your system
can boot even if you forget to generate the config. Never the less you should
take time and migrate the configuration to be automatically generated, because
next time GRUB 2 is installed it will use automatic generation and ignore
GRUB Legacy files.
# grub2-mkconfig -o /boot/grub2/grub.cfg
Tweaking the options is to be done in the /etc/default/grub file.
Simple text file configuration with description of some default values.
All the options are described in grub2 info pages.
This file is created by Gentoo and if you find an interesting option not used
in there just open a bugreport (possibly with a patch).
Sometimes, if automatic detection of GRUB 2 does not suffice, the file
/etc/grub.d/40_custom should be used to store custom entries. Full
description how to configure such with examples can be found in grub2 info
pages.
menuentry "My Shiny Gentoo Kernel" {
set root=(hd0,1)
search --no-floppy --fs-uuid --set <UUID>
linux /boot/gentookernel-5.3.2-generic root=UUID=<UUID>
initrd /boot/initrd.img-5.3.2
}
Remember to replace the <UUID> with your device UUID.