Handbook Talk:AMD64/Installation/Bootloader
Before creating a discussion or leaving a comment, please read about using talk pages. To create a new discussion, click here. Comments on an existing discussion should be signed using
~~~~:
A comment [[User:Larry|Larry]] 13:52, 13 May 2024 (UTC) : A reply [[User:Sally|Sally]] 07:12, 18 April 2025 (UTC) :: Your reply ~~~~
Some closed discussions have been moved to an archive subpage: Handbook Talk:AMD64/Installation/Bootloader/Archive.
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)
- We could cover this case when we're finished migrating to DSP... --Maffblaster (talk) 23:23, 25 January 2024 (UTC)
- What's DSP? — 12:44, 1 April 2024 (UTC)
- Found it: https://uapi-group.org/specifications/specs/discoverable_partitions_specification/ — Waldo Lemmer 20:45, 1 April 2024 (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)
- Sure. Your suggestion has been implemented: Special:Diff/1260946/1271970. Thanks! --Maffblaster (talk) 11:47, 31 December 2023 (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)
- You are correct; great observation. This suggestion has been implemented here: Special:Diff/1266908/1271967. --Maffblaster (talk) 11:37, 31 December 2023 (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)
- This discussion is now out of date, since we're revising the Handbook for Discoverable Partition Specification and now provide instructions to create and mount the ESP at /efi and (eventually) to issue: {{{1}}}
- We'll presume /boot is a part of the rootfs now (up to the sysadmin per the disk partitioning section). We will take your recommenation to remove
--target=x86_64-efinow: Special:Diff/1271967/1271974 --Maffblaster (talk) 12:03, 31 December 2023 (UTC)
- We'll presume /boot is a part of the rootfs now (up to the sysadmin per the disk partitioning section). We will take your recommenation to remove
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.
- These steps have been added in the various relevant Handbook sections. See Special:Diff/1273054/1274826 and Special:Diff/1275047/1275048. Thanks Nowa Ammerlaan (AndrewAmmerlaan) ! --Maffblaster (talk) 23:19, 25 January 2024 (UTC)
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 ;-)
- Thank you! --Maffblaster (talk) 12:04, 31 December 2023 (UTC)
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)
- I believe the efibootmgr section of the AMD64 handbook is looking better now. Please reopen if I am mistaken. Thank you! --Maffblaster (talk) 12:34, 31 December 2023 (UTC)
- It is still wrong. It must be: --unicode "initrd=\efi\initramfs-genkernel-amd64-6.1.38-gentoo"
- (Look at " BEFORE initrd and NO ' BETWEEN =\efi AND if it should fit to the text it must be also in \efi\ directory)
- Complete: efibootmgr --create --disk /dev/sda --part 1 --label "gentoo" --loader "\efi\gentoo\bzImage.efi" --unicode "initrd=\efi\initramfs-genkernel-amd64-6.1.38-gentoo"
- Pietinger 15:00, 31 December 2023 (UTC)
- Fixed in Special:Diff/1273081
- Thanks! --Xarvatium (talk) 22:01, 7 January 2024 (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
Thanks! --SamWilsn (talk) 03:43, 4 December 2023 (UTC)
- Great tip. It seems systemd-boot was mentioned a few months ago, and that section presumes the reader will visit the article to read more when pursuing it as the system's secondary bootloader. Your suggestion can't hurt and has been implemented here: Special:Diff/1271977/1271978. Thanks! --Maffblaster (talk) 12:18, 31 December 2023 (UTC)
In bootloader config. make a note telling users that they may need to recompile systemd with the boot USE flag, or just compile systemd with the boot use flag by default
If a user wishes to use sytemd-boot with EFI, they will have to compile sytemd with the boot use flag, otherwise they will get an error telling them that there are missing files / no directory for EFI in systemd.
I propose that either a note is added notifying users that they may need to recompile or compile systemd with the boot USE flag. Or that the systemd stage 3s compile their systemd with the boot flag by default.
The gnuefi flag has been removed as far as I can see and has been replaced with boot instead, as I checked the USE flags for systemd and could find no gnuefi flag :).
--Alexx52 (talk) 01:28, 25 July 2024 (UTC)
Adding a hint to changing the root password
Some may forgot to change the root password or change the root password for the livecd environment and not in chroot.
I would like to suggest an important block to be sure to to set the according to Configuring the system > System information > Root password.
--SartorialDaemon (talk) 21:47, 2 March 2025 (UTC)