Handbook Talk:AMD64/Full/Installation
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.Some closed discussions have been moved to an archive subpage: Handbook Talk:AMD64/Full/Installation/Archive.
improve suggested partitions and use of grub-install
In my opinion, the handbook (amd64) is a bit confusing regarding partitioning.
First of all, I think it should try to keep the "parted" and "fdisk" examples as coherent as possible. Furthermore, it would be preferable (more complete) to explain how to install Gentoo to a device that can then be booted both with UEFI and Legacy BIOS. Emphasis should be put on GPT, letting go MBR.
So here are my suggestions.
1) the "fdisk alternative" described at https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Installation#Alternative:_Using_fdisk_to_partition_the_disk warns that fdisk might still have bugs when supporting GPT (-t gpt). However, it does use an example partitioning scheme with bios boot and boot (see below).
2) the "fdisk alternative" starts with this partitioning scheme:
/dev/sda1 BIOS boot partition /dev/sda2 Boot partition
and then ends telling the user to mark partition 1 (BIOS boot) for UEFI and create partition 2 as "boot".
The end results is:
[BIOS boot] /dev/sda1 1 3 5198+ ef EFI (FAT-12/16/32) [boot/grub] /dev/sda2 * 3 14 105808+ 83 Linux [swap] /dev/sda3 15 81 506520 82 Linux swap [root] /dev/sda4 82 3876 28690200 83 Linux
3) in this section (https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Installation#Applying_a_filesystem_to_a_partition) the handbook suggests to format partition 2 as ext2:
# mkfs.ext2 /dev/sda2
4) in this other section (https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Installation#Using_UEFI) the handbook *suggests* to do the following:
# mkfs.fat -F 32 /dev/sda2
This suggestion is incoherent with point 2. It also doesn't guide the user to a UEFI installation.
5) There's one thing the user should be aware of and is not clearly stated in the handbook. For a UEFI installation, the live install system (or the liveCD) must boot via UEFI, not Legacy BIOS. In fact, it can happen that the BIOS will silently fail to boot a UEFI device and switch to booting via Legacy BIOS. Also, it should be clear to the reader that the current Gentoo Minimal CD is UNABLE to boot with UEFI (work in progress). Either use the LiveDVD or another system such as SystemRescueCD. In any case, the handbook should suggest to check for the existance of /sys/firmware/efi as soon as the live system has booted. The user cannot install to a UEFI-bootable HDD if the live medium hasn't been booted with UEFI. In particular, the user will fail to grub-install with EFI, as suggested in the handbook.
6) The default partitioning scheme described at https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Installation#Default_partitioning_scheme differs with point 2 because:
[BIOS boot] /dev/sda1 (bootloader) 2M BIOS boot partition [boot/grub or UEFI] /dev/sda2 ext2 (or fat32 if UEFI is being used) 128M Boot/EFI system partition
7) The parted instructions at https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Installation#Default:_Using_parted_to_partition_the_disk suggest to install BIOS boot on partition 1 and boot on partition 2. In case the user wants to boot with UEFI, the handbook suggests to set UEFI on partition 2 (boot). This is incoherent with point 2.
8) Finally, I think it would be better if the handbook could explain how to install to a UEFI&BIOS-aware device.
There should be two scenarios:
a) user wants to boot with ONLY UEFI or ONLY Legacy BIOS:
in this case, use:
a1) if Legacy BIOS:
- boot with BIOS (not UEFI)
- check /sys/firmware/efi does not exist
- partitions:
[BIOS boot] /dev/sda1 [boot/grub] /dev/sda2 (ext2)
- filesystem:
# mkfs.ext2 /dev/sda2 # mount /dev/sda2 /boot
- install bootloader:
# grub-install /dev/sda
a2) if UEFI:
- boot with UEFI (not BIOS)
- check /sys/firmware/efi exists
- partitions:
[BIOS boot] /dev/sda1 [UEFI] /dev/sda2 (fat32)
- filesystem:
# mkfs.fat -F 32 /dev/sda2 # mount /dev/sda2 /boot
- install bootloader:
# grub-install --target=x86_64-efi --efi-directory=/boot /dev/sda
(actually, grub-install /dev/sda should be enough)
b) user wants to boot with BOTH UEFI AND Legacy BIOS:
b1) grub and efi on different partitions:
- boot with UEFI (not BIOS)
- check /sys/firmware/efi exists
- partitions:
[BIOS boot] /dev/sda1 [UEFI] /dev/sda2 (fat32) [boot/grub] /dev/sda3 (ext2)
- filesystem:
# mkfs.fat -F 32 /dev/sda2 # mkfs.ext2 /dev/sda3 # mount /dev/sda3 /boot # mkdir /boot/efi # mount /dev/sda2 /boot/efi
- install bootloader:
# grub-install --target=x86_64-efi --efi-directory=/boot/efi /dev/sda
( actually, grub-install --efi-directory=/boot/efi /dev/sda should be enough)
# grub-install --target=i386-pc /dev/sda
b2) grub and efi on same partition:
- boot with UEFI (not BIOS)
- check /sys/firmware/efi exists
- partitions:
[BIOS boot] /dev/sda1 [UEFI/boot/grub] /dev/sda2 (fat32)
- filesystem:
# mkfs.fat -F 32 /dev/sda2 # mount /dev/sda2 /boot
- install bootloader:
# grub-install --target=x86_64-efi --efi-directory=/boot /dev/sda
( actually, grub-install /dev/sda should be enough)
# grub-install --target=i386-pc /dev/sda
--Vieri (talk) 11:17, 17 February 2017 (UTC)
DavidC improvements section
Preparing the disk
As I'm reading through this doco I'm writing a bunch of suggestions, some of which are sure to be misguided, so the only discussion I require is "yes/no/maybe later". Hopefully some of this helps but I know not all of it will be implemented. Anyways: Prior to "Introduction to block devices" it would be nice if there was a title that said something like preparing the disk, since that is what is referred to above in the document. DavidC (talk) 17:57, 18 November 2017 (UTC)
Open more than one chroot terminal
I'd probably get the user to chroot a couple terminals at least because then they would be able to do some reading while something is going on it another window, or easily compare say the output of lspci to what they're inputting in makeconfig, etc. DavidC (talk) 15:13, 19 November 2017 (UTC)
We mention screen for this purpose, but I have also have added a tip to explictly show readers how to switch between the seven available terminals: Special:Diff/1015767/024956. --Maffblaster (talk) 20:35, 29 October 2021 (UTC)
This and that
I am lost at Handbook:AMD64/Full/Installation#Introduction_to_block_devices. Looking at "If that is the case, it might be..." I understand what "that" case is, but when it says "In this case, launch..." I do not understand what "this" case is. Perhaps after "using the MBR format." A sentence could be added directing MBR users to "Default partitioning scheme". Someone suggested this be split into 3 sections "bios with mbr, efi with gpt, bios with gpt" DavidC (talk) 19:37, 18 November 2017 (UTC)
I am overwhelmed with mirrors
"links https://www.gentoo.org/downloads/mirrors/" So if you follow the first link for Canadians, you end up going to a LONG list of files and it's not entirely clear what to download (even if you follow it all the way to Gentoo, so it's probably best just to link people straight to https://gentoo.org/downloads/. DavidC (talk) 19:58, 18 November 2017 (UTC)
- If you are referring this section, there are no instructions to download anything from the mirrors directly. It's just giving an example on how to use links to determine what mirror URLs are avaialble. No where in the instruction are you supposed to download anything in this section. --Maffblaster (talk) 20:35, 29 October 2021 (UTC)
Variables
"variables which impacts" --> "impact" DavidC (talk) 20:02, 18 November 2017 (UTC)
- Fixed. See Special:Diff/1023606/1024968. --Maffblaster (talk) 20:35, 29 October 2021 (UTC)
Path differences for examples
"To keep the settings, Portage reads in the /etc/portage/make.conf file" ok so this line is talking about what is currently /mnt/gentoo/etc/... but the light blue section afterwards refers to /mnt/gentoo/usr/share/... explicitly, as does the black section starting with nano -w, so there should be consistency across all those three things. DavidC (talk) 20:14, 18 November 2017 (UTC)
I seems like you're splitting hairs on ths one. The tip is about Portage. The path is different because you're operating out of an extracted state3 during this section of the handbook. I'll just change it to make.conf to avoid confusion. See Special:Diff/1023606/1024968. --Maffblaster (talk) 20:35, 29 October 2021 (UTC)
Custom prompt is reverted
After "root #eselect locale set 9", the shell tells the user to run something like . /etc/profile, which results in removing the custom prompt "(chroot)" and it's a little disconcerting. So I think the best option here is to tell the user not to follow the prompting of the shell before giving the set 9 command. Further, afterwards there is a black box that has maybe 3 commands in it separated by & and those commands could easily be given as a series of single lines, which would probably be better. DavidC (talk) 14:53, 19 November 2017 (UTC)
Current USE flags in profile
In the USE flag section, it might be a good idea to suggest something like <profile_file> | grep ^USE >> <make.conf> so that people can see their profile USE flags at the same time that they're putting in their custom values; they would have to comment it out if they did that, though. DavidC (talk) 15:08, 19 November 2017 (UTC)
- I really like the idea of explaining how to view USE flags already set in the profile. I'll implement something like this soon. --Maffblaster (talk) 20:35, 29 October 2021 (UTC)
devtmpfs cannot be unselected
" [*] Maintain a devtmpfs filesystem to mount at /dev" You can not unselect this, therefore this section can be removed safely. DavidC (talk) 15:19, 19 November 2017 (UTC)
- We'll safely leave it. --Maffblaster (talk) 09:28, 20 February 2023 (UTC)
Blank line requested
"Executable file formats / Emulations --->" Put a blank line prior to this to strongly indicate that it's denested. DavidC (talk) 16:04, 19 November 2017 (UTC)
GRUB install issue
For grub-install with EFI, please include the 2 steps for EFI vars. Otherwise, grub-install will silently fail. From https://wiki.gentoo.org/wiki/Efibootmgr#Creating_a_boot_entry:
root #mount | grep efivars efivarfs on /sys/firmware/efi/efivars type efivarfs (ro,relatime)
root #mount -o remount,rw -t efivarfs efivarfs /sys/firmware/efi/efivars
— The preceding unsigned comment was added by Dman777 (talk • contribs) 19:27, December 18, 2017
- This should NOT be the case when using official Gentoo installation live images. We do cover that in the GRUB install section, we just don't currently specify the
--typeoption, as your example does. --Maffblaster (talk) 09:39, 20 February 2023 (UTC)
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)