Handbook Talk:AMD64/Installation/Bootloader

GRUB UEFI instructions needed
New to wiki and gentoo, so sorry if this is the wrong place/I format this comment wrong.

In any case, the grub instructions should either link to GRUB or talk about how you have to emerge with GRUB_PLATFORMS="efi-32 efi-64" (one of those two) and possibly use --target x86_64_efi. This took me much too long to figure out as a noob.

Mordocai (talk) 07:39, 24 May 2015 (UTC)


 * Hi, thanks for the comment. The instructions for GPT/EFI have been cleaned up quite a bit. We also have links to the GRUB2 article in various places. I believe this resolves your issue. Kind regards, --Maffblaster (talk) 18:14, 3 October 2016 (UTC)
 * I believe that current instruction may be missleading. Based on gentoo discord none of newcommers ware able to make GRUB2 use EUFI without external help.
 * Wiki is not really good place to ask questions :D Ask rather on Discord: https://discordapp.com/invite/gentoo or #gentoo on IRC https://www.gentoo.org/get-involved/irc-channels/ and recommend changes based on that experience on wiki if you want. :) Kreyren (talk) 21:57, 26 August 2018 (UTC)


 * The mentioned GRUB_PLATFORMS now has a default of "pc efi-64" when using AMD64. This covers both PC-BIOS and most UEFIs on the market today.  I consider this topic done as a result. --Grknight (talk) 19:12, 27 October 2018 (UTC)

Grub2 install UEFI fails from minimal CD
When using UEFI: grub2-install --target=x86_64-efi --efi-directory=/boot

Note: this step fails when running from a minimal CD booted in BIOS (legacy) mode. This is because the efivars module is not available there. See for example

A fix for this is to install from a Gentoo Hybrid ISO (LiveDVD) booted through UEFI.

I got caught by this. Can we at least put a warning on the page that this step will not work work if when installing from the minimal installation CD? This has now been open for more than a year. I used a systemrescue USB to finalize my installation.-Arch dude (talk) 04:45, 4 March 2017 (UTC)


 * Yes, pretty please. There should be a warning about the Minimal CD in BIOS mode not containing  module. As a EFI novice, I've spent around 3 hours on this issue! I also ended up with SystemRescue USB in EFI boot mode.


 * The other thing is that the  spits a lot of   although it finishes with a line containing  . The GRUB installation failed because of the efivars module but the output is confusing... Yuri69 (talk) 22:49, 18 April 2017 (UTC)


 * The minimal ISO properly supports UEFI and efivars since September 2018. --Grknight (talk) 18:49, 27 October 2018 (UTC)

GRUB2 all platforms
It should be made very clear that the boot partition should be mounted prior to using the grub2-install command. Without mounting the boot partition, grub2-install will say it has installed successfully with no error, leaving you with a non-bootable system.


 * Pickledpiper, Please remember to sign your comments on discussion pages. :) I will look into your concern. If a note is necessary, then I will add one. :) --Maffblaster (talk) 17:39, 4 November 2015 (UTC)


 * Looking into this more, the Mounting section of the Disks part deals with mounting . We (the Handbook maintainers) expect newcomers to read the Installation section of the Handbook from beginning to end, section-to-section. As long as they follow the necessary steps (which are provided) the partition is available. I may consider adding a note to remount the partition if the system is using one, but for now I'm marking this discussion as done. --Maffblaster (talk) 19:15, 3 October 2016 (UTC)

syslinux should be proposed here
Why syslinux has never be proposed as bootloader for Gentoo Linux? It is a mature, versatile, complete and lightweight bootloader. Also, it respect the KISS principle.

There are reason to exclude it?


 * I would agree, syslinux has stayed contemporary and is probably more widely used than LILO. Reason we haven't touched it is because of lack of interest and/or manpower on the docs/wiki teams. I would consider adding a least a reference to it as a possible alternative. One reason I don't believe it's wise to include an entire section here in the handbook is that there's not a simple, straightforward way to install syslinux because there are a lot of different options. What would you suggest as the command(s) required to install/configure it if was included in the Handbook for MBR or GPT/EFI systems? --Maffblaster (talk) 18:33, 3 October 2016 (UTC)


 * There has been no responses here by for more than one quarter of a year (3) months.  I am going to close review mentioning syslinux in the Handbook and close this discussion. --Maffblaster (talk) 21:31, 20 April 2017 (UTC)

Incomplete umount on recent kernels
Recent kernels mount some "cgroup" stuff within the chroot in, which causes the final to fail due to the mounted sub paths. I'd suggest to replace

with

which recursively umounts everything mounted in.


 * Good suggestion. I'll need to make sure though that recursive unmounts work properly. An alternative that I found online was to use something like the following:
 * --SwifT (talk) 08:44, 3 October 2016 (UTC)
 * --SwifT (talk) 08:44, 3 October 2016 (UTC)


 * I think we'd all agree the Handbooks should be kept as simple as possible, but not simpler. :) I'm liking the option and would vouch for that as long as it works as implied. I ran a test on my system and it worked nicely for me. Can you also test, ? --Maffblaster (talk) 15:57, 3 October 2016 (UTC)


 * Since there's been no reply for a few months, and this worked well for me on official installation media in my testing environments, I will implement the suggestion. Kind regards, --Maffblaster (talk) 14:02, 1 January 2017 (UTC)

GRUB2 os-prober
I think it's worth mentioning that the os-prober package needs to be emerged for the grub installer to detect other OSes (Windows for eg)


 * I mentioned it in a tip. Thanks for the suggestion! --Maffblaster (talk) 18:12, 3 October 2016 (UTC)

Incomplete Grub2 EFI installation command
When using

the GRUB2 installation is not complete. Booting this system fails.

would be the correct way to install GRUB2 (if you chose grub as your bootloader id).

— The preceding unsigned comment was added by Lukiwuki (talk • contribs) October 24, 2016


 * I'm sorry if you are confused. The default EFI menu choice will be Gentoo and not grub unless you change it like you mentioned.  This should be sufficient enough for the average person to figure out what is booting. --Grknight (talk) 18:51, 27 October 2018 (UTC)

Ran into the same problem as LukiWuki. If '--bootloader-id=...' is not specified for 'grub-install' then it will not invoke 'efibootmgr' to actually install a boot entry into the onboard UEFI firmware and so grub won't be available at boot (afaict this is why sys-boot/efibootmgr is a DEPEND of sys-boot/grub?). Once the complete grub-install command is used, the boot entry can be seen with 'efibootmgr' (used '--bootloader-id=GRUB' in this instance).

Hi Guys, I also ran into this problem with, it only installs grub into  , but no UEFI NVRAM entry added (can be checked via  ), a complete command would be:

This {https://blog.uncooperative.org/blog/2014/02/06/the-efi-system-partition/ article} has detailed information about the booting behavior of UEFI. Could someone update the manual accordingly? I see three discussions under this page talking this problem. Shunlir (talk) 14:34, 1 March 2020 (UTC)

Information for systemd users needed in Grub2 section
I would at least link to: Systemd

Also adding a mention about the usage of GRUB_CMDLINE_LINUX would probably help a lot to other people to migrate from old grub specially when needing to append kernel options

Thanks, — The preceding unsigned comment was added by Pacho (talk • contribs) November 17, 2016‎


 * Hi, please remember to sign your contributions to discussion pages so we can track how long the discussion has been open. :). I will look into this and mark it closed when I finish. --Maffblaster (talk) 20:54, 9 February 2017 (UTC)


 * With the sysv-utils USE default on recent systemd installs, is this still necessary? --Grknight (talk) 19:25, 27 October 2018 (UTC)

A critical typo at grub-install for UEFI
It currently has a space at --target=x86 64-efi.[1] It should have an underscore, ie. grub-install --target=x86_64-efi --efi-directory=/boot

Could someone with editing rights please fix this ASAP? Thanks, --Fcl (talk) 19:17, 11 February 2017 (UTC)


 * Yes, sorry. Fixed it yesterday. Thanks for closing! --Maffblaster (talk) 15:42, 15 February 2017 (UTC)

GRUB2 (UEFI) bootable file
Some UEFI firmware expects a bootable file at a known location (Which isn't configured using the default GRUB2 UEFI instructions). When rebooting after the installation the error "Please select a proper boot devices" would show up. This can be fixed by using the following command:

This copies the grubx64 bootfile to the known location so the UEFI firmware is like "Hey, I found a boot file at the expected location!" .

Hopefully this can be implemented in the docs so other people know what to do when experiencing this problem.


 * Hi, yes, I can add this to the AMD64 Handbook. Your path for the destination is not correct, though, you're missing the boot/ directory. I can fix this when I add it to the Handbook, though. Thanks! --Maffblaster (talk) 00:15, 21 April 2017 (UTC)

Problem still exists
I am going through an install now and ran into the same problem. I had to do the following:

After I did this the motherboard recognized the drive as being bootable, and I was able to boot up the system. — The preceding unsigned comment was added by Hij (talk • contribs) 30 November 2017

Grub2 EFI misses correct platform with empty GRUB_PLATFORMS
I am installing a Gentoo to EFI host (Installed quite many Gentoos before, but not that many on EFI hosts). According to handbook, I should use 'GRUB_PLATFORMS=""' in make.conf. But this installed only "i386-pc" platform for Grub2: ''ls -l usr/lib/grub/ total 24 drwxr-xr-x 2 root root 24576 Feb 23 17:15 i386-pc''

So I did get this error, when trying to install Grub2: ''grub-install: error: /usr/lib/grub/modinfo.sh doesn't exist. Please specify --target or --directory.''

So after I fixed the platforms var in make.conf to GRUB_PLATFORMS="efi-64 efi-32 pc" and re-emerged grub2, I was able to install grub2, with "grub-install --target=x86_64-efi --efi-directory=/boot" (it still needed the target).

And yes, I was making the installation through common minimal-installation-cd, through server's one-time boot menu as legacy boot. Even if this was the reason why grub2 didn't install efi platform with empty "" in GRUB_PLATFORMS, it should be noted in the handbook (as there are probably more people than just me, who do it like this). Probably one-liner hint would do it. Or maybe there could be a hint in the point of handbook where grub2 is being installed, that EFI users installing grub2 should check that efi-32 and/or efi-64 are included in USE arguments of grub2 installation. --Arackhaen (talk) 16:29, 23 February 2017 (UTC)


 * This must have been fixed in the past as no where in the document currently lists an empty GRUB_PLATfORMS value. --Grknight (talk) 18:54, 27 October 2018 (UTC)

Broken internal link
The link doesn't work anymore. Please fix it to

Fturco (talk) 15:53, 16 April 2017 (UTC)


 * Fixed. --Maffblaster (talk) 08:57, 22 February 2022 (UTC)

Fix capitalization
Please fix "(I.E. install itself on the disk)" to "(i.e. install itself on the disk)". id est (i.e.) should be written with lowercase letters. Fturco (talk) 16:01, 16 April 2017 (UTC)


 * Updated. Thanks. --Grknight (talk) 18:58, 27 October 2018 (UTC)

CONFIG_CMDLINE
"The Linux kernel itself can be booted immediately, and additional kernel command-line options can be built-in to the Linux kernel (there is a kernel configuration option called CONFIG_CMDLINE that allows the user to specify boot parameters as command-line options). Even an initramfs can be 'built-in' to the kernel."

Please add the parts written in bold.

Fturco (talk) 16:10, 16 April 2017 (UTC)

Also might be worth to mention which overruns which? CONFIG_CMDLINE vs. parameters passed by bootloader. --Zucca (talk) 17:51, 16 April 2017 (UTC)


 * Fixed. --Maffblaster (talk) 08:59, 22 February 2022 (UTC)

"Presuming the ESP is mounted at /boot/efi (as suggested earlier)"
Handbook:AMD64/Blocks/Bootloader states Presuming the ESP is mounted at /boot/efi (as suggested earlier) Where in Handbook has this been suggested???

As can be seen from Handbook:AMD64/Installation/Disks, the ESP is and next chapter, Handbook:AMD64/Installation/Base, mounts it to So it is mounted to, not to. Mounting ESP at needs some more explanation.--Charles17 (talk) 10:22, 29 May 2017 (UTC)

--Charles17 (talk) 06:55, 27 June 2017 (UTC)
 * Explanation is given in the b1) grub and efi on different partitions section. But not so easy to read from the main text.


 * Thanks for adjustments done.--Charles17 (talk) 15:36, 9 August 2017 (UTC)

How is GRUB2 the default bootloader?
I find it odd that this article calls GRUB2 the default bootloader when:

1. It does not come pre-installed in the stage3 tarball. A default I would have expected to have found here. For example, you could call nano the default text editor of Gentoo as it is included in the stage3 tarball by default and is extensively referred to in the documentation. nano is also the default editor as the $EDITOR environment variable is automatically set to /bin/nano in stage3 (as opposed to Vi which is also included in the stage3). OpenRC/SysV init are another example of how if it's included in the stage3 tarball (I am aware that systemd stage3 tarballs exist, but where not otherwise specified the tarball is assumed, by default, to have OpenRC/SysV init setup as its init system) by default it is the default.

2. Gentoo is a do-it-yourself (DIY) and extensively-customizable distribution, so users are free to make all their own choices. Not sure how someone can call something the default unless it is the only option available in the Gentoo official repository (the Portage tree) or in the stage3 tarball.

Anyone care to clarify to me why GRUB2 is called the default? Is it just because it is the option recommended by Gentoo developers? Brenton (contribs · email · talk) 06:30, 21 June 2017 (UTC)
 * In the Handbook, the word "default" just denotes the way most people will probably want to do something. (As for GRUB2 not being in stage3, neither are the alternatives.) - dcljr (talk) 23:43, 10 July 2018 (UTC)

typo in copy command
Hi, there are two typos in the command that copies efi file to an alternative path. You have /efi/efi in the source and destination whereas it has to be this way: cp /boot/efi/gentoo/grubx64.efi /boot/efi/boot/bootx64.efi --Wowpetr (talk) 00:10, 12 July 2017 (UTC)


 * See Handbook_Talk:AMD64/Installation/Bootloader. --Charles17 (talk) 04:14, 12 July 2017 (UTC)

openrc efivars
As per gentoo-dev mailing list,

The documentation should be updated to say that with OpenRC 0.28 that you'll have to remount efivars as RW before you can install the bootloader (e.g., grub-install)

The command I use locally to remount rw (since I have configured efivars to be mounted read-only in fstab) is

mount -o remount,rw /sys/firmware/efi/efivars

from mattst88@gentoo.org

--Rage (talk) 01:16, 13 July 2017 (UTC)


 * Completed in a previous edit. --Grknight (talk) 19:00, 27 October 2018 (UTC)

Example LILO configuration needs updating
Handbook:AMD64/Full/Installation

Or at least a mention of  option which significantly reduces boot time

Source

--- /etc/lilo.conf	2018-01-19 19:08:07.166557719 +0300 +++ /etc/lilo.conf.new	2018-01-19 18:59:12.212245569 +0300 @@ -2,6 +2,7 @@    prompt                    # Give the user the chance to select another section timeout=50               # Wait 5 (five) seconds before booting the default section default=gentoo           # When the timeout has passed, boot the "gentoo" section +compact                  # This drastically reduces load time and keeps the map file smaller image=/boot/vmlinuz-3.16.5-gentoo label=gentoo           # Name we give to this section

Thyr (talk) 15:50, 19 January 2018 (UTC)


 * Updated with a small comment change. --Grknight (talk) 19:05, 27 October 2018 (UTC)

Verify that UEFI is available on the system
Recommends adding command  in Installation section for user to diagnose if its system is able to use UEFI with the instructions to allow it in BIOS or verify on manufacturer's site.

Based on experience on Discord none was able to make gentoo run on UEFI grub without help from staff. This modification should make the process easier.

Possibly to add this information to introduction too so that new user woudn't have to restart the installation.

— The preceding unsigned comment was added by Kreyren (talk • contribs) 26 August 2018


 * The Bootloader section is already too late to have this command. If anything, it should be in an earlier page at or before the layout decision. --Grknight (talk) 19:07, 27 October 2018 (UTC)

No mention of GRUB_PLATFROMS="pc" for BIOS
BIOS systems require Grub to be installed with USE flag "pc" or they fail to boot


 * It will fail at  as well.  What is the likelihood of a new user changing GRUB_PLATFORMS in make.conf?  The profile defaults to both UEFI (efi-64) and BIOS (pc) on AMD64.  You have to actively disable BIOS support to not include it. --Grknight (talk) 16:50, 9 September 2019 (UTC)

Indentation error in section 'Default: GRUB2 / Install / When using UEFI:'
The last three paragraphs ('Some motherboard...', 'root # ...', 'This creates ...') should indented as the previous ones, since they clearly belong to the 'When using UEFI' branch.

--Mike155 (talk) 02:32, 10 November 2019 (UTC)

Grub "No Error" message regarding "EFI variables are not supported on this system."
Hi Handbook team, Is it possible to add a note regarding Grub's response

Installing for x86_64-efi platform. EFI variables are not supported on this system. EFI variables are not supported on this system. Installation finished. No error reported.

message when running the handbook suggested command

grub-install --target=x86_64-efi --efi-directory=/boot

As a UEFI novice, I interpreted "No error" as nothing amiss and the unsupported variables as inconsequential. I then got an unbootable system.

Ideally the handbook could offer a command to check it the system is currently booted as UEFI, as I thought it was based on the notes regarding the minimum ISO download page and its support of UEFI since late 2018.

In the end I found that viewing the partition information via fdisk showed the boot USB was not booted in true UEFI mode and I could then investigate how to do so.

This was made harder by my BIOS not having the option to just disable Secure Boot. Instead I had to change the OS settings from Windows Secure to Other.

Thank you for considering my suggestion. --Bluenuht (talk) 22:00, 14 November 2019 (UTC)


 * You have to understand that it did succeed except for one bit. Modifying your firmware to load grub directly.  By adding the noted   option, for when the system does not find the grub EFI, your system would boot. --Grknight (talk) 17:40, 15 November 2019 (UTC)

May need clarification in section 'Default: GRUB2 -> Emerge'
This section seems confusing when user visits it first time. It doesn't clearly distinguish what instructions to follow with UEFI, from that to follow with BIOS. Will it be clearer, if, 1) both BIOS and UEFI follow 'emerge --ask --verbose sys-boot/grub:2', 2) move 'A note for UEFI users...' into a note block, 3) move 'If GRUB2 was somehow emerged without enabling...' into another note block? Shunlir (talk) 02:06, 28 February 2020 (UTC)

Refind, other alternative to Grub
rEFInd is another alternative to Grub (as boot manager only) that could be mentionned here. --Akar (talk) 03:10, 1 June 2020 (UTC)

efibootmgr: unicode and root
I suggest to update command examples by adding   as in example here: EFI stub kernel. I use on Without , I had kernel panic: VFS: cannot open root device "(null)" or unknown-block(0,0): error -6 Please append a correct "root=" boot option; here are available partitions: … ---[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0) ]-- Without, kernel starts by EFI without additional arguments. Although in the output additional arguments looks good. --Vazhnov (talk) 12:02, 27 September 2020 (UTC)

Final prompt example is inaccurate
At Handbook:AMD64/Installation/Bootloader

As far as I'm aware it should be more like:

Jmcb (talk) 13:57, 28 December 2021 (UTC)

Wrong drive partition selected when creating boot entry with efibootmgr
In Handbook:AMD64/Installation/Bootloader the command for creating the boot entry and adding it to the UEFI firmware is:

but earlier in Handbook:AMD64/Installation/Disks the default partitioning scheme sets the partition 1 as the boot/EFI system partition. As such the correct command should be:

Cyph3r (talk) 18:21, 26 March 2022 (UTC)

grub-install efi-directory incorrect canonical default path
Fact: The default parameter for grub-install is --efi-directory=/boot/efi

Issue: our parameter of --efi-directory=/boot/ is self-inconsistent with the handbook partition section

In the handbook, here, we overrided it to /boot (wrong to assume). My theory is this path of setting the EFI dir to /boot likely referred to previous scenarios where /boot and /boot/efi were having been combined. Today most people are going for seperate partitions, and run into problems with this section, especially when it conflicts with prior instructions. In the handbook, earlier partitions section, it was advised to create this System ESP a FAT32 EFI partition, and create a different /boot partition, which allows /boot to be very linuxy (ext4/BTRFS/etc), which is not what the efi dir is.

Fact: A requirement is for the --efi-directory to point to the System ESP (the vfat/FAT32 partition). The default, /boot/efi/ Fact: A second requirement is for that partition to contain an EFI directory - so you end up with /boot/efi/EFI (fyi, thats why it repeats like that).

Also: the --target=x86_64-efi will also be auto-detected if the system is right, and if not, it will give an error and tell you to pass the --target parameter. By pre-emptively forcing the parameter, we are losing the opportunity for a sanity check warning of the user not having the right EFI modules, EFIvars, booted into a UEFI itself to begin with, etc. IMO a concious decision should be required when passing the param because it equals forcing the param and skips the auto-detection, something that could be a useful debug step.

TLDR: grub-install will auto-detect --efi-directory=/boot/efi, so it should be omitted when you are mounting the ESP @ /boot/efi , which is most people. grub-install also auto-detects --target=x86_64-efi for active EFI sane systems, so it can be omitted also, to check the env for sanity IMO "grub-install" with zero parameters - should be listed as the primary option for UEFI. Add a caveat saying change the dir ONLY if unusual

Genr8 (talk) 09:14, 1 March 2023 (UTC)