Handbook Talk:AMD64/Installation/Bootloader
This is a Talk page - please see the documentation about using talk pages. Add newer comments below older ones, sign comments using four tildes (
~~~~), and indent successive comments with colons (:).
Add new sections at the bottom of the page, under a heading (== ==). Please remember to mark sections as "open for discussion" using {{talk|open}}, so they will show up in the list of open discussions.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#UEFI_with_GPT 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 Mordocai , 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)
- Matthew Marchese (Maffblaster) 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.
- Mordocai 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. — The preceding unsigned comment was added by HTS (talk • contribs) 15 October 2015
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
efivarsmodule. 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
grub-installspits a lot ofEFI variables are not supported on this systemalthough it finishes with a line containingNo error reported.. 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. — The preceding unsigned comment was added by Pickledpiper (talk • contribs) 4 November 2015
- 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 /boot. 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 /boot 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? — The preceding unsigned comment was added by Hujuice (talk • contribs) 23 December 2015
- 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 Hujuice 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 /mnt/gentoo, which causes the final umount to fail due to the mounted sub paths. I'd suggest to replace
root #umount /mnt/gentoo{/boot,/sys,/proc,} with
root #umount -R /mnt/gentoowhich recursively umounts everything mounted in /mnt/gentoo. — The preceding unsigned comment was added by Sprittwicht (talk • contribs) 18 May 2016
- 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:
root #grep /mnt/gentoo /proc/mounts | cut -f 2 -d" " | sort -r | xargs umount -n- --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 umount -R 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, Sven Vermeulen (SwifT) ? --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) — The preceding unsigned comment was added by Amity88 (talk • contribs) 4 July 2016
- 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
root #grub-install --target=x86_64-efi --efi-directory=/bootthe GRUB2 installation is not complete. Booting this system fails.
root #grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=grubwould 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).
root #efibootmgr -v
BootCurrent: 0000
Timeout: 2 seconds
BootOrder: 0000,0002,0003
Boot0000* GRUB HD(1,GPT,89058682-a234-495f-9062-7cecc811960d,0x800,0x82000)/File(\EFI\GRUB\GRUBX64.EFI)
Boot0002* Windows Boot Manager HD(1,GPT,89058682-a234-495f-9062-7cecc811960d,0x800,0x82000)/File(\EFI\MICROSOFT\BOOT\BOOTMGFW.EFI)— The preceding unsigned comment was added by Shiznix (talk • contribs) 18 August 2019
Hi Guys,
I also ran into this problem with grub-install --target=x86_64-efi --efi-directory=/boot, it only installs grub into /boot/EFI/gentoo/grubx64.efi, but no UEFI NVRAM entry added (can be checked via efibootmgr -v), a complete command would be:
root #grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=GentooThis {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)
- Interesting. I will look into reproducing this issue. It would seem it never has been an issue for me any of the dozens of times I've ran through the handbook for EFI installations... Wonder if it depends on how well the motherboard's system firmware implements the UEFI specification? --Maffblaster (talk) 21:19, 15 September 2023 (UTC)
- Update: I could not reproduce the exact issue. At this point GRUB automatically adds an entry in the nvram (efibootmgr -v) list with the title of "gentoo", associated to the correct boot entry in the firmware loader (which is HD(1,GPT 1, ...). It WORKSFORME. :) Kind regards, --Maffblaster (talk) 21:45, 15 September 2023 (UTC)
Information for systemd users needed in Grub2 section
I would at least link to: Systemd#GRUB_2
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 Pacho Ramos (Pacho) , 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)
- I believe this discussion is stale. Closing for now. --Maffblaster (talk) 21:15, 15 September 2023 (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:
root #cp /boot/efi/gentoo/grubx64.efi /boot/efi/efi/bootx64.efi 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. — The preceding unsigned comment was added by Jordyzomer (talk • contribs) 18 February 2017
- Hi Jordyzomer , 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:
root # mkdir /mnt/gentoo/boot/EFI/BOOT
cp /mnt/gentoo/boot/EFI/gentoo/grubx64.efi /mnt/gentoo/boot/EFI/BOOT/BOOTX64.EFI
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 Handbook:AMD64/Installation/Bootloader#Default:_Using_GRUB2 link doesn't work anymore. Please fix it to Handbook:AMD64/Installation/Bootloader#Default:_GRUB2
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)
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#Install 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#Using_UEFI, the ESP is /dev/sda2
root #mkfs.fat -F 32 /dev/sda2and next chapter, Handbook:AMD64/Installation/Base#Mounting_the_boot_partition, mounts it to /boot
root #mkdir /bootroot #mount /dev/sda2 /bootSo it is mounted to /boot, not to /boot/efi. Mounting ESP at /boot/efi needs some more explanation.--Charles17 (talk) 10:22, 29 May 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.
--Charles17 (talk) 06:55, 27 June 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#.22Presuming_the_ESP_is_mounted_at_.2Fboot.2Fefi_.28as_suggested_earlier.29.22. --Charles17 (talk) 04:14, 12 July 2017 (UTC)
- This is no longer an issue since we recommend creating the firmware file with GRUB using
--removableas an option now. --Maffblaster (talk) 21:12, 15 September 2023 (UTC)
- This is no longer an issue since we recommend creating the firmware file with GRUB using
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)
Example LILO configuration needs updating
Handbook:AMD64/Full/Installation#Configure_2
Or at least a mention of compact option which significantly reduces boot time
--- /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)
Verify that UEFI is available on the system
Recommends adding command ls -ld /sys/firmware/efi && echo efi || echo mbr 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 — The preceding unsigned comment was added by Mole (talk • contribs)
- It will fail at grub-install 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)
- This has been fixed. They're all the same level of indentation and better delineated now. Thank you! --Maffblaster (talk) 21:11, 15 September 2023 (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
--removableoption, 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)
- I do not think what was pointed out here is still unclear since many edits have been made since Feb 2020. We'll close this one up for now. Please correct me if I'm mistaken. --Maffblaster (talk) 21:09, 15 September 2023 (UTC)
Refind, other alternative to Grub
rEFInd is another alternative to Grub (as boot manager only) that could be mentioned here. --Akar (talk) 03:10, 1 June 2020 (UTC)
- Thanks. Yes, you're right. We could cover it. Our goal in this section, however, is not to cover every possible option, but a few of the contemporary major ones and one of the older ones (LILO - since it historically has been included within the handbook). We want to avoid inducing analysis paralysis, so we'll major on the majors. Interested parties can still look into rEFInd themselves decide if they want to use it on their system. Kind regards, --Maffblaster (talk) 21:07, 15 September 2023 (UTC)
efibootmgr: unicode and root
I suggest to update efibootmgr command examples by adding --unicode 'root=PARTUUID=…' as in example here: EFI stub kernel.
I use sys-kernel/gentoo-kernel-bin on
Without 'root=PARTUUID=…', 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 --unicode, kernel starts by EFI without additional arguments. Although in the efibootmgr -v output additional arguments looks good.
--Vazhnov (talk) 12:02, 27 September 2020 (UTC)
Final prompt example is inaccurate
At Handbook:AMD64/Installation/Bootloader#Rebooting_the_system
As far as I'm aware it should be more like:
(chroot) livecd #exitlivecd ~#cd
livecd ~#umount -l /mnt/gentoo/dev{/shm,/pts,}
livecd ~#umount -R /mnt/gentoo
livecd ~#rebootJmcb (talk) 13:57, 28 December 2021 (UTC)
Wrong drive partition selected when creating boot entry with efibootmgr
In Handbook:AMD64/Installation/Bootloader#Alternative_2:_efibootmgr the command for creating the boot entry and adding it to the UEFI firmware is:
root #efibootmgr --create --disk /dev/sda --part 2 --label "Gentoo" --loader "\efi\boot\bootx64.efi"but earlier in Handbook:AMD64/Installation/Disks#Introduction_to_block_devices the default partitioning scheme sets the partition 1 as the boot/EFI system partition. As such the correct command should be:
root #efibootmgr --create --disk /dev/sda --part 1 --label "Gentoo" --loader "\efi\boot\bootx64.efi"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)
- The earlier sections of the AMD64 Handbook use a single partition for both /boot and the EFI System Partition for simplicity and consistency sake. The bootloader section must continue this. Therefore, --efi-directory must be specified if using the Handbook exactly. --Grknight (talk) 13:40, 1 March 2023 (UTC)
Suggestion to add systemd-boot as alternative
I suggest to add systemd-boot as an alternative for UEFI systems using distribution kernels. This boot loader greatly simplified the config for me as someone who hasn't installed Gentoo for many years. It does not need any changes to secure boot, just editing the loader config file to ensure the correct root= option is passed to the kernel and initrd.
Suggested text for systemd-boot section:
A good alternative to GRUB for modern UEFI systems is systemd/systemd-boot. It works well with distribution kernels.
To install it, no new packages need to be installed, just enable the correct USE flag:
- For OpenRC, enable USE variable
bootfor sys-apps/systemd-utils as follows:root #echo sys-apps/systemd-utils boot >> /etc/portage/package.use/01-systemd-bootroot #emerge --oneshot --update --changed-use sys-apps/systemd-utils
- For Systemd, enable USE variable
gnuefifor sys-apps/systemd as follows:root #echo sys-apps/systemd gnuefi >> /etc/portage/package.use/01-systemd-bootroot #emerge --oneshot --update --changed-use sys-apps/systemd
The distribution kernels will call sys-kernel/installkernel-systemd-boot to install the kernel and initrd into the correct directory in the ESP. The only changes needed are to install systemd-boot EFI executable to the ESP using bootctl install, and to adjust the kernel option line in the loader.conf entry for the distribution kernel.
What parameter removable does
"This creates the default directory defined by the UEFI specification, and then copies the grubx64.efi file to the 'default' EFI file location defined by the same specification." => ... and rename "grubx64.efi" to "bootx64.efi" (because this is the name every UEFI must find - even without an explicit entry in its UEFI boot table). Usually "bootx64.efi" is used only when trying to boot from an USB stick (or CD ROM) because there cannot be a boot entry in UEFI table; and therefore there must be a name every UEFI recognizes always - this is also the background of the name of this parameter - its usually used when I want install grub to an USB stick ;-)
Alternative 2: efibootmgr - Why EFI\BOOT and grubx64.efi?
This section's intent seems to be helping readers setup their computers so that the UEFI firmware can directly boot an EFI stub kernel. If that's so, why use grubx64.efi, i. e. GRUB's PE32+ executable's name, as cp's destination filename? Also, directory \EFI\BOOT in the ESP has a special purpose defined by the UEFI specification, so I think that it is not a good recommendation to tell users to install files there.
Therefore, I would suggest replacing the EFI stub's name with vmlinuz.efi or something like that, and to use destination directory \EFI\gentoo instead. And finally, the ESP's mountpoint and partition number should be consistent with the rest of the handbook That is:
root #mkdir -p /efi/efi/gentooroot #cp /boot/vmlinuz-* /efi/efi/gentoo/vmlinuz.efiroot #efibootmgr --create --disk /dev/sda --part 1 --label "gentoo" --loader "\efi\gentoo\vmlinuz.efi"GuillermoDH (talk) 15:10, 23 September 2023 (UTC)
- The chapter Alternative 2: efibootmgr is wrong because we want install a kernel and not grub as bootmanager ! Today I have updated the wiki article Efi stub. I suggest to copy from there into this page ... or only link to it. pietinger 14:36, 24 September 2023 (UTC)
systemd-boot: make sure the new entry exists
I've run through the installation steps for systemd-boot several times now, and somehow each time I've managed to reboot without a systemd-boot entry for my new kernel getting created. I'm sure the fault is mine, but I think it would be useful to add something like this to the systemd-boot alternative section:
Before rebooting, verify that a new entry exists using:
root #bootctl listIf using a distribution kernel and no new entry exists, ensure sys-kernel/installkernel-systemd is installed, and run:
root #emerge --config sys-kernel/gentoo-kernel