Handbook Talk:AMD64/Full/Installation
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]] 01:27, 23 April 2025 (UTC) :: Your reply ~~~~
Some closed discussions have been moved to an archive subpage: Handbook Talk:AMD64/Full/Installation/Archive.
Alternative: Using Genkernel
Offering some feedback as a newbie who hasn't even successfully gotten his first install working. (But I will! :)
The genkernel section starts out this way:
If a manual configuration looks too daunting, then using genkernel is recommended. It will configure and build the kernel automatically.
The impression is that if we've gone through the kernel configuration info and found it overwhelming (as I did), then this is perhaps the way to go. On the other hand, the Genkernel wiki page (which was not linked in this section, though probably should be as I took some time to find it), says:
It is a common misconception that genkernel will "automatically" generate a custom kernel configuration. genkernel automates the kernel build process and assembles the initramfs, but does not generate a custom kernel configuration file. If a kernel configuration is not provided, genkernel will use a generic kernel configuration file which will produce a general purpose kernel suitable for daily usage (at the expense of a large modular kernel).
What I've had to learn through my experiments is that in some cases - mine, though I can't say how many - genkernel will miss basic necessary modules, and manual kernel configuration will be necessary. Since the --menuconfig option to genkernel allows this, I would like to suggest:
1. Instead of starting out with manual configuration and scaring us noobs, begin with `genkernel all`. Then, add in some information about `genkernel --menuconfig` and a link to the Genkernel wiki page. (The --menuconfig section is far too short, and offers no explanation that if offers a menu similar to the manual kernel configuration's "menuconfig", or even that it should be run as `genkernel --menuconfig all`. Nor that we can or what it might mean to add other switches: `genkernel --luks --menuconfig all`).
2. On that Genkernel wiki page, give (perhaps outside links to) substantial resources regarding kernel configuration.
a. I still can't grok the relationship between a module name and a kernel switch. Sometimes they seem related, but it's certainly not 1-1.
b. Help us understand: if we run lsmod and see a module (eg btrfs) and then many other modules that it depends on (eg. xor, xxhash, ...), do we need all the dependencies in the kernel or initramfs?
c. Explain if, when a component is not built in, there is some way to tell genkernel to put that module in the initramfs. I've disassembled my initramfs, and I find some odd smattering of modules in there. Many that genkernel had built and should be there, aren't. I'd like to tell it to add them.
3. Give manual kernel configuration as the optional approach; but now you're already gone into necessary information on kernel switches/ configuration.
I'm too new to change anything here, so I won't, but I did want to offer this bit of input.
Thanks for all your work here!
Diagon (talk) 02:51, 6 December 2020 (UTC)
- This issue should be resolved since distribution kernels are now offered as the first option for kernel management in the Handbook. Some of the stuff you commented about concerning genkernel is more about kernel configuration management in general, and could be added somewhere in the Kernel/Configuration article (or a sub-article). I'll try to write up something in genkernel concerning the modules included in the initramfs. They are presently pulled into the initramfs via genkernel's /usr/share/genkernel/defaults/modules_load and per-arch modules_load files. This is controlled via the RAMDISKMODULES value in the /etc/genkernel.conf file. Thanks for the feedback! --Maffblaster (talk) 09:55, 20 February 2023 (UTC)
Missing boot options?
The minimal iso seems to be lacking the "dosshd" and the "passwd=" boot options, they also do not show up in the iso's help section. — The preceding unsigned comment was added by Terminalkuki (talk • contribs) 2022-04-25
- Interesting, yes, the handbook documents those options here and I wonder if they have been removed from the live images? If this is the case, then it's an issue to pursue with the RelEng project. Please enter a bug at bugs.gentoo.org. If they decide to not put them back, then we can remove them from the handbook. Thank you! --Maffblaster (talk) 09:45, 19 February 2023 (UTC)
Typo
Handbook:AMD64/Full/Installation#Filesystems paragraph 1, sentence 2: word "found" repeated. Thanks to "codex" for report on IRC. -- Ris (talk) 20:17, 7 August 2022 (UTC)
- Fixed with this change over all handbooks --Grknight (talk) 00:48, 8 August 2022 (UTC)
- Thanks Grknight. "codex" just reported another one: Handbook:AMD64/Full/Installation#Unpacking_the_stage_tarball, second paragraph, 1st word: "Verity". Maybe that should be "Verify that" ? -- Ris (talk) 01:54, 8 August 2022 (UTC)
- Fixed as well. Special:Diff/1104805. Thanks! --Maffblaster (talk) 07:39, 8 August 2022 (UTC)
Improve the Choosing a stage tarball section
Personally, I can see multiple issues with this section.
It feels like there is no sufficient introduction/motivation why to care about the tarball selection - a piece of it seems to be used as an intro to the Multilib subsection. Would it be possible to add an introductory piece?
Missing description of the available tarballs. A majority of inexperienced user following the Handbook would be using the LiveCD, which implies browsing a mirror with links. This way, there is not much context besides the tarball names. It seems there are currently 19 current-stage3-amd64-* tarballs present. Some of them are currently described in the section, but many, such as LLVM, Musl, hardened, or Systemd merged-usr, are not. Any further links/pointers in the handbook section would IMHO improve the user experience.
Yuri69 (talk) 11:19, 10 December 2023 (UTC)
- I've made improvements to this section, and have broken the whole handbook section into more digestible sections. I think presenting information exhaustively for every option (including advanced ones which fall out of scope of the handbook) may make choosing a stage file difficult. If you have any suggestions for improvements beyond the current ones, please share them. Zen desu (talk) 05:03, 8 January 2024 (UTC)
Improve "Optional: Signed kernel modules" section
Tip: To get this fixed sooner, use {{Proposal}}.
I disabled secure boot to do my install, but followed the instructions to create a signing key for later use. I've now found the time recently to re-enable secure boot. Unfortunately, the key I generated is now out of date a month later. It would be useful to include -days 9999 or something similar as an argument in the instructions for the creation. The Secure Boot wiki page Secure_Boot includes a note saying "Because the process of rekeying Secure Boot is rather cumbersome, an expiry period of 10 years is typically used, it can be reduced or extended, but must be rekeyed when the keys expire" This would make the the wiki more consistent and improve the user experience, especially new users overall IMHO
--Octonoodle (talk) 05:35, 22 March 2024 (UTC)
Remind users to disable Secure Boot when booting from install media fails
Tip: To get this fixed sooner, use {{Proposal}}.
Section 6 "Booting" should hold a hint to disable Secure Boot in BIOS, in case the install medium is recognized as bootable device, but won't boot to GRUB.
Mmanico (talk) 11:36, 24 March 2024 (UTC)
Random assortment of proposed changes
Tip: To get this fixed sooner, use {{Proposal}}.
The partition and fstab sections refer to /boot on legacy and /efi on UEFI systems. I understand this is a relatively recent change, so a lot of places still assume the boot partition is /boot.
Handbook:AMD64/Full/Installation > Creating the EFI System Partition (ESP) mentions "First create a small EFI system partition, which will also be mounted as /boot.". As this is the EFI partition, change /boot to /efi. (Also add those fancy {{Path|hilights}})
Handbook:AMD64/Full/Installation#Generation says to just run genkernel --mountboot --install all.
It should mention to run genkernel --bootdir=/efi --mountboot --install all instead for efi, unless the recommended configuration BOOTDIR="/efi" is added to /etc/genkernel.conf. See also Genkernel > Changing the boot directory to /efi, where I added a chapter about that.
Besides that, the overview at the top of "Kernel configuration and compilation" mentions "(optionally, but not enabled by default) an initramfs file". The command mentioned below generates an initramfs by default though, genkernel --mountboot --install kernel (kernel instead of all) would be needed to not build initramfs.
Redjard 2024-04-19 16:11 (UTC)
Edit: 2024-04-19 20:09 (UTC)
Handbook > GRUB > UEFI systems grub-install --efi-directory=/efi installs all files except grubx64.efi in /boot rather than /efi. Is that not a dangerous configuration, that will break for most? I propose recommending grub-install --efi-directory=/efi --boot-directory=/efi instead.
grub-mkconfig -o /efi/grub/grub.cfg doesn't run without symlinking /boot into /efi. I also had to update that command from the wiki provided version using -o /boot/grub/grub.cfg
Skipping emerge-webrsync
The title "Optional: Updating the Gentoo ebuild repository" should be "Optional (not if you skipped emerge-webrsync): Updating the Gentoo ebuild repository". And it should be placed right after emerge-webrsync section. So when it says "you can happily skip to next section", people go to 'emerge --sync'.
Siakc (talk) 13:10, 10 January 2025 (UTC)
- You should have not skipped the
emerge-websyncas outlined in the section:
Suppose there is a need for the latest package updates (up to 1 hour), then use emerge --sync. This command will use the rsync protocol to update the Gentoo ebuild repository (which was fetched earlier on through emerge-webrsync) to the latest state.
Sorry, but I think we make this very clear especially when you remember there is no optional text on running emerge-websync.
- I did not skip the section. I skipped it when reached the part "Readers who have no network or bandwidth restrictions can happily skip down to the next section.". Which clearly says you can skip this section. It is at least confusing if not incorrect (which I think it is). By fixing this you may save many people get into problem installing Gentoo and many explaining that they must either run `emerge --sync` or `emerge-webrsync`. I suggest asking a third opinion if you are not convinced.
- I think I agree with you now, looks like we forgot to clean up the text when we added the ability to skip sections in the install process. Nice find and thanks for reporting it :)