User:Jerichowasahoax/EFI Install

From Gentoo Wiki
Jump to:navigation Jump to:search
Warning, this page is a work in progress by jerichowasahoax (talk | contribs). Treat its contents with caution.

This guide attempts to provide an installation guide for Gentoo systems on UEFI compatible systems. This guide has the following objectives:

  • It will be more suitable for general installations than Sakaki's EFI Install Guide, and therefore (hopefully!) easier to support in #gentoo (webchat).
  • It will restrict itself to what you can find within the main Portage tree (no custom scripts, no overlays), and will not make any assumptions on how you wish to run your system.
  • It will serve *only* as a guide to UEFI support. You will still have the option to combine UEFI with other technologies (LUKS, LVM, et al), which are documented elsewhere on the wiki.

This guide assumes you have a cursory understanding of the Gentoo Handbook installation process. Additionally, this guide assumes your platform is amd64. (32-bit UEFI does exist, but you likely are not using it.) If this guide does not specify any details for a step in the handbook installation process, proceed as normal. (For instance, no special action needs to be taken to extract the stage3 archive on EFI systems)


You will need:

  • A live Linux medium with EFI support (the Gentoo minimal ISO does *not* qualify). An Ubuntu or Red Hat image is recommended; both will provide you with a graphical desktop and partitioning tools and so forth, but more importantly, both support UEFI booting out of the box, and recent versions are even signed with Microsoft's keys meaning you do not have to (initially) disable Secure Boot.
  • If you wish to continue using Secure Boot, you will need a motherboard that allows you to import your own keys (app-crypt/efitools contains "KeyTool.efi", which can be booted to for this purpose). Otherwise, you will need to disable Secure Boot.

Beginning the install

First, boot to your installation medium and configure your network. Then, partition your disks, keeping in mind the following caveats:

  • The partition table *must* be GPT.
  • You must include a FAT32 partition (preferably towards the beginning of the disk) to put your bootloader on, as UEFI does not understand any other file system. In addition, you may need to set the "boot" and "esp" flags on this partition, especially if you intend to install Microsoft Windows alongside Gentoo. GNU Parted (and it's GUI GParted) can do this. If you install Microsoft Windows first, you can simply reuse the existing partition, labeled as "EFI System Partition" or similar.
  • The rest of the partitioning may be done as normal, according to your particular needs and desires.

This guide assumes the following basic filesystem layout:

Device Filesystem Mount point
/dev/sda1 FAT32 /boot
/dev/sda2 Swap partition -
/dev/sda3 ext4 /

Base system

After extracting the stage3, the following packages need to be installed in addition to your cron daemon, syslogger, et al:

  • sys-boot/efibootmgr - to add your bootloader to UEFI's NVRAM entries. This program is also capable of changing your system's boot order from userspace, which may be of interest to users who dualboot Microsoft Windows.
  • app-crypt/efitools - for KeyTool.efi, if you intend to use Secure Boot and your motherboard does not provide its own mechanism for adding trusted keys.
  • dev-libs/openssl or dev-libs/libressl - for generating Secure Boot keys. One of these packages is likely already installed in the stage3 or will be pulled in as a dependency for some other package. Both are listed here for completeness.

Kernel configuration

KERNEL EFI support
Processor type and features --->
  [*] EFI runtime service support

Firmware drivers --->
  EFI (Extensible Firmware Interface) Support --->
    <*> EFI Variable Support via sysfs

All other EFI related settings are either optional (unless you intend to use the EFI stub feature) or will be automatically enabled for you anyway.


GRUB2 (recommended)

GRUB 2 (sys-boot/grub) is the recommended choice of bootloader for UEFI setups, for the following reasons:

  • GRUB has been widely used since the MBR days, and is still universally understood by the Gentoo community, making it easier to receive support if something goes wrong.
  • Support for multiple kernels in /boot, in case you build a kernel and it panics, allowing you to fallback to your previous known-good kernel.
  • Support for changing the command line on the fly, without rebuilding your kernel.

It is imperative that you install GRUB 2, which is in slot 2, instead of the version in slot 0 (commonly known as "GRUB Legacy"). Only GRUB 2 supports EFI booting.

FILE /etc/portage/make.conf
root #emerge grub:2
root #grub-install --efi-directory=/boot
root #grub-mkconfig -o /boot/grub/grub.cfg
Make sure your EFI system partition is mounted at /boot before running grub-install, because GRUB needs to copy some files to that partition. If you choose to mount your EFI partition elsewhere (/boot/efi is a common location), update your value for --efi-directory accordingly.
You may need to run grub2-install and grub2-mkconfig instead, if for some reason you've emerged it with USE="multislot".

If all has gone well, grub-install will have already updated your NVRAM and placed itself into the boot order for you. You can check with efibootmgr:

root #efibootmgr
BootCurrent: 0000
Timeout: 3 seconds
BootOrder: 0000
Boot0000* Gentoo

If for some reason, grub-install has not updated your NVRAM, it is possible to do this yourself.

The -d argument specifies the disk that the boot loader is installed on (/dev/sda, for instance), and the -p argument specifies which partition. So, if your EFI system partition was /dev/sda1, you would use -d /dev/sda -p 1. See the manpage for efibootmgr(8) for more information.
root #efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\gentoo\\grubx64.efi -L "Gentoo Linux"

EFI Stub (advanced)

If for some reason you would prefer your motherboard to directly load your kernel (which is only really useful for embedded systems), it is possible.

This article is a stub. Please help out by expanding it - how to get started.