Handbook Talk:AMD64/Installation/Kernel

fstab for swap
User should be informed about the syntax for swap in /etc/fstab or he/she might make a mistake since it not mentioned anywhere.

--Kreyren (talk) 00:05, 17 September 2018 (UTC)

EDIT- its on the next page, but its not mentioned on fstab wiki page nor for genkernel.. --Kreyren (talk) 00:06, 17 September 2018 (UTC)


 * As you have found, it is documented and does not be listed on the kernelpage. --Grknight (talk) 17:57, 5 November 2018 (UTC)

Encrypted root device
It should be thought about a hint in the Documentation for using a encrypted root device. — The preceding unsigned comment was added by PatrickE (talk • contribs)


 * Although important, disk encryption is a more advanced topic and we will not be able to cover all the options in the Handbook. The point of the Handbook is to give our community an overview of how to install a basic Gentoo installation. Feel free to see of the disk encryption articles other places around the wiki. Thank you! --Maffblaster (talk) 07:05, 26 October 2021 (UTC)

NVMe SSDs
Anywhere in the 'genkernel' section should be mentioned that you need to put nvm block device drivers into the kernel (not as a module) so that initramfs can detect the root drive. (I could do this). — The preceding unsigned comment was added by PatrickE (talk • contribs)


 * Current versions of genkernel build and load NVMe by default. No need for additional notes in the Handbook --Grknight (talk) 19:59, 25 June 2020 (UTC)

UEFI confusion
I believe the "With UEFI systems" should be changed to "With UEFI systems using EFI stub" or simply "When using EFI stub" (where it tells you to copy the kernel to /boot/efi/boot/ ). This caused problems and confusion when installing my first UEFI system. GRUB2 will automatically take care of creating the directories and copying the correct file to the location for GRUB2 to work when you run grub2-install (later in the handbook, configuring the bootloader). A friend whom I helped install Gentoo also found this confusing so I thought I would look into getting it changed.

Thanks!


 * Thanks,, we'll review and make adjustments as appropriate! Please be sure to sign your comments using the button in the menu bar above! :) --Maffblaster (talk) 19:50, 22 May 2016 (UTC)

Stripping debugging symbols from the kernel
I am assuming most people new to gentoo are not going to start debugging the kernel. After all, the handbook audience is not only kernel hackers. Hence, it would be neat to add explanation how to strip the debugging symbols from the kernel and the modules. This saves some disk space, and sheds some more light on compiling the kernel. It would be good to add a note about this right below

make && make modules_install

Stating one can strip the modules from debugging symbols using:

make INSTALL_MOD_STRIP=1 modules_install --Oz123 (talk) 21:19, 8 June 2016 (UTC)


 * The Handbook is not the place to mention specifics on kernel configuration. Entire books could be written on the subject. It would be better for our readers to look at the Kernel article and the various sub-articles beneath it (see Kernel/Configuration for what you're mentioning).

USB 3.0
I believe the handbook should mention that modern systems likely have USB 3.0, and so users should turn on USB 3.0 support in the kernel:

Device Drivers --> USB support --> xHCI HCD (USB 3.0) support

which is actually off by default. Without this, USB devices, including internal ones like some webcams, will not be detected at all, and `lsusb` won't work.


 * The Handbook is not the place to mention too many specifics on kernel configuration. Entire books could be written on the subject. It would be better for our readers to look at the Kernel article and the various sub-articles beneath it (see Kernel/Configuration for what you're mentioning).


 * Please don't forget to sign your comments on talk pages. --Maffblaster (talk) 20:49, 18 August 2016 (UTC)


 * I will end up adding a snippet for USB 3.0 since the other USB drivers are mentioned. --Maffblaster (talk) 22:10, 20 April 2017 (UTC)

Remind/note user to enable SCSI support
I think there might be a need for a small note to make sure that user enables CONFIG_BLK_DEV_SD to be able to use any normal storage media. I know it needs to be in there, but as evidence points out - it can be left out by a mistake as it isn't a dependency (an automatic one) for normal SATA functionality. I don't know how often people stumble into this problem, but I guess it wouldn't hurt anyone to mention about it?

--Zucca (talk) 12:19, 12 December 2016 (UTC)


 * It has been added. Thanks! --Maffblaster (talk) 22:42, 20 April 2017 (UTC)

Typo
"CONFIG_TMPF" should be fixed to "CONFIG_TMPFS". Fturco (talk) 15:27, 16 April 2017 (UTC)

Edit: also "we enables" should be fixed to "we enable" as well Fturco (talk) 15:28, 16 April 2017 (UTC)


 * I think you could go ahead and fix typos. Typo fixes don't add anything that needs much of a review. ;) --Zucca (talk) 16:48, 16 April 2017 (UTC)


 * It would be wonderful if I could do that, but unfortunately I don't have permissions to edit the Handbook. Fturco (talk) 20:24, 16 April 2017 (UTC)


 * Oh. Didn't notice this was handbook article. My bad. --Zucca (talk) 22:13, 16 April 2017 (UTC)


 * Fixed. Thanks! --Maffblaster (talk) 22:07, 20 April 2017 (UTC)

Suggested change to kernel build process
Configuring and building the kernel could be done as a limited user. This would prevent bugs in the kernel build process from affecting the rest of the install. It also sets up the system to allow future kernel builds/upgrades to follow the same pattern preventing kernel build process bugs from affecting the whole system including user home areas.

My suggested additions are as root create a limited user to build the kernel e.g. kernel_builder as root chown /usr/src/linux to the kernel build user

then as the kernel build user create /usr/src/linux/My_INSTALL_PATH and /usr/src/linux/My_INSTALL_MOD_PATH configure and build kernel export INSTALL_PATH=/usr/src/linux/My_INSTALL_PATH export INSTALL_MOD_PATH=/usr/src/linux/My_INSTALL_MOD_PATH make install make modules_install

then as root copy kernel and modules to required folders

Advantages - whole build process including installing modules is done as a limited kernel build user. Other tools/packages looking for things in /usr/src/linux will find them.


 * , Thank you for the suggestion. Building the kernel as a non-root user would would be a great tip to include in the Kernel article. You should totally do it. The purpose of the Handbook is not to describe the safest method, or even to describe best practices in security. The purpose is to detail, in a general and efficient manner, how to get Gentoo up and running on a system. Adding a user is covered as a final step in the installation process, so it would not be useful to create an additional 'kernel build' user. I will not be including this submission in the Handbook; as I said you should add it to the Kernel article. Kind regards, --Maffblaster (talk) 23:11, 25 July 2017 (UTC)

Update command for entering configuration
I noticed the command for entering the configuration is currently: root # make menuconfig I know this isn't the Arch wiki, but on their page they specifically mention to use `make nconfig`.

Indeed, using make nconfig on kernel 4.11.4 revealed some options that `make menuconfig` does not show (like `native` for the processor family to enable -march=native, and `BFQ I/O scheduler` for I/O schedulers).

Best regards,

Emegir (talk) 14:53, 13 June 2017 (UTC)


 * Hi Elegir, it is not really true that provides different options that are not available otherwise. Arch probably provides these, however Gentoo considers these 'experimental' options. They are made available in Gentoo by enabling the   USE flag on the  package. Hope this helps! Kind regards, --Maffblaster (talk) 23:52, 24 July 2017 (UTC)

find kernel modules
For years I manually stripped the path and the .ko from the kernel modules with the file search. Now I found a better way:

find /lib/modules/4.4.75-gentoo/ -type f -iname '*.o' -or -iname '*.ko' -exec basename {} \; |awk -F. '{ print $1 }'

prints:

vboxdrv instead of: find /lib/modules/4.4.75-gentoo/ -type f -iname '*.o' -or -iname '*.ko' /lib/modules/4.4.75-gentoo/misc/vboxdrv.ko

Maybe this could be on the manual? Elmar283 (talk)


 * Hello,, Thank you for the input. I'm not sure I understand exactly what issue this solution solves, but I don't think it's necessary to include something like this in the handbook. Please do add it (perhaps in a Troubleshooting section!) in our Kernel article! Kind regards, --Maffblaster (talk) 20:35, 24 July 2017 (UTC)


 * It could safe people a lot of time. I had tot strip down the path and the .ko all the time after I had build the modules. With the above line you won't have to do that anymore. You can just copy the output and put that in the kernel modules file.

Elmar283 (talk) 19:22, 25 July 2017 (UTC)


 * I completely understand the purpose of the script and as I said, it is good input. With that being stated, I do not believe it is something that must be included in the Handbook. This is for additional customization, including installing software (like VirtualBox as you showed in your example) that is not necessary to get a system up and running. Getting the system up and running with Gentoo is the purpose of this Handbook. Please add this tip to the Kernel or VirtualBox article; I'm sure others will find it useful as well. Kind regards, --Maffblaster (talk) 23:04, 25 July 2017 (UTC)


 * It has nothing to do with Virtualbox. That's just one of the modules I installed on my linux box on my VirtualBox. I goes for all the modules you install. I also have linux systems without Virtualbox. What if you compile your kernel and you have 50 installed as modules. Then you'll have to erase 50 times the path and the .ko. That will take you a lot of time, while if you type

find /lib/modules/4.4.75-gentoo/ -type f -iname '*.o' -or -iname '*.ko' -exec basename {} \; |awk -F. '{ print $1 }'

it will strip the path and the .ko. So you will get:

snd-hda-core

instead of

/lib/modules/4.4.8-hardened-r1/kernel/sound/hda/snd-hda-core.ko

And that time the amount of kernel modules you have installed. And a lot people who follow the handbook will not know that they can strip the '/lib/modules/4.4.8-hardened-r1/kernel/sound/hda/' and the '.ko' width some pipes and commands.

Elmar283 (talk) 20:22, 26 July 2017 (UTC)


 * True, but I'm still not following the point of why stripping is needed here. Marking this discussion as resolved (after a few years later). --Maffblaster (talk) 06:30, 26 October 2021 (UTC)

`make menuconfig` error
make menuconfig return make: *** No rule to make target 'menuconfig'. Stop.

UPDATE: fixed by emerge --ask sys-kernel/gentoo-sources But now next problem: init/Kconfig:1875: can't open file "arch/Kconfig"

Vitaly-zdanevich (talk) 09:06, 22 July 2017 (UTC)

This is not for here. Go to https://forums.gentoo.org

Elmar283 (talk) 15:04, 23 July 2017 (UTC)


 * Hi,, Elmar is correct, asking for support can be done on IRC, the mailing list, or on the forums. Not here on the wiki. This is a place to improve the documentation. Kind regards, --Maffblaster (talk) 20:32, 24 July 2017 (UTC)

Problem with emerge genkernel?
There may be a problem with the instructions for using genkernel. I ran into this when trying emerge genkernel while following the instructions in this Handbook. It looks like someone had a similar problem on the Forums. I did get past it but it had me stumped for awhile. This is my first time installing so I could have easily messed up a previous step.

(chroot) livecd / # emerge --ask sys-kernel/genkernel

* IMPORTANT: 13 news items need reading for repository 'gentoo'. * Use eselect news read to view new items.

These are the packages that would be merged, in order:

Calculating dependencies... done! [ebuild N     ] app-arch/cpio-2.12-r1  USE="nls" [ebuild N     ] sys-kernel/linux-firmware-20180730  USE="-savedconfig" [ebuild N     ] virtual/libudev-232  USE="-static-libs -systemd" ABI_X86="(64) -32 (-x32)" [ebuild  R    ] sys-apps/util-linux-2.32-r4  USE="static-libs* udev*" [ebuild N     ] sys-kernel/genkernel-3.5.3.3  USE="firmware -cryptsetup (-ibm) (-selinux)"

The following USE changes are necessary to proceed: (see "package.use" in the portage(5) man page for more details) >=sys-apps/util-linux-2.32-r4 static-libs
 * 1) required by sys-kernel/genkernel-3.5.3.3::gentoo
 * 2) required by sys-kernel/genkernel (argument)

Would you like to add these changes to your config files? [Yes/No] n (chroot) livecd / #

Garbanzo (talk) 06:19, 17 August 2018 (UTC)


 * Hello, this is not a problem with genkernel. This output was simply stating genkernel required  to be set on the  package; probably since some of the utilities were going to be bundled into initramfs. You can read more about USE flags in the Working with Gentoo section of the Handbook. Hope this helps! --Maffblaster (talk) 06:37, 26 October 2021 (UTC)

Various fixes
1. In  config sample the   section should be indented as it belongs to.

2. In, the   should be under   section instead.

Anon (talk) 11:55, 17 August 2019 (UTC)


 * 1. Has been fixed. See Special:Diff/1018950/1023486 2. IA32 Emulation is no longer referenced in the AMD64 or X86 Handbooks. Thanks, ! --Maffblaster (talk) 06:42, 26 October 2021 (UTC)

Microcode
From a troubleshooting section on IRC, I found out that microcode doesn't seem to get a mention in the handbook.

I think it'd fit best at the end of this page (given it's loaded by the kernel and may be built into it), like with the firmware hint.

Sam (talk) 00:51, 7 March 2020 (UTC)


 * Thanks,, I have finally implemented your suggested change... Apologies it took so long! Feel free to edit if you think it's missing something. See Special:Diff/1023486/1023498. --Maffblaster (talk) 07:02, 26 October 2021 (UTC)

Firmware install
I don't know if this applies to the automatic kernel configuration but, for the manual configuration:

In the section Installing firmware, the instructions warns that some hardware need additional firmware for it to work. For a newcomer, this last section makes the impression that the command emerge --ask sys-kernel/linux-firmware is the solution. Please correct me if I am wrong but in order for it to work the user must: 1) specify in the kernel which firmware is to be loaded (along with the path) and 2) re-compile and re-install the kernel. But this last step is cumbersome because previously in this section, the user has already compiled and installed the kernel. I suggest the former section to be moved before the later as an optional step IF the user needs some firmware. A single example could be given that any almost laptop user would need: intel firmware for wifi devices. For any other hardware, remind the user the of the lspci tool and other articles that might help.--Neyuru (talk) 03:23, 6 April 2020 (UTC)


 * As for "specify in the kernel which firmware is to be loaded (along with the path)", this is not required when the driver is a module. It is recommended that any driver that needs firmware to be a module  in order to load from the file system as necessary. Not every driver needs to be but it certainly will help. --Grknight (talk) 19:48, 25 June 2020 (UTC)


 * is correct in that it is best practice to use firmware built-in to the kernel binary... It's worth considering moving the firmware section and mentioning certain hardware requires firmware to be loaded at boot time (wireless cards, graphics cards, CPUs (microcode), etc. --Maffblaster (talk) 07:09, 26 October 2021 (UTC)


 * I have made the following edit along these lines (Special:Diff/1023498/1023513). Goal will be to point readers in the right direction so that they only need to compile the kernel once. It still needs some work. or, want to review and add some stuff? Thanks! --Maffblaster (talk) 07:23, 26 October 2021 (UTC)

using the handbook as reference for kernel compilation
If i cd /usr/src/linux on an already installed system and follow the instructions to manually compile the kernel from the handbook, i'll be changing the .config of the current ketnel, not the newly emerged one.

It may be frustrating.

Vesperto (talk) 00:30, 23 April 2020 (UTC)


 * This page of the Handbook is designed for installation of a new system's kernel. We have Kernel/Upgrade for tips on moving to a new version. --Grknight (talk) 19:52, 25 June 2020 (UTC)

Parallel compilation for kernel?
When instructing people on how to compile the kernel, it might be helofyk to include the -jN option in the instructions for manual compilation, as well as the --makeopts=-jN for genkernel. If the machine has multiple cores, they might as well be put to work. AyasakiHayate (talk) 17:43, 25 June 2020 (UTC)


 * This exists as a note and has for a good while now. As for genkernel, recent defaults are to use -j$(nproc).  Anyone who wishes to change the default is welcome to on the command-line or in genkernel.conf --Grknight (talk) 19:45, 25 June 2020 (UTC)

gentoo-kernel{,-bin} inclusion
I think sys-kernel/gentoo-kernel{-bin,} can safely be included here as another alternative. Ajak (talk) 02:10, 24 July 2020 (UTC)


 * Distribution kernels are now listed. --Grknight (talk) 14:41, 11 January 2022 (UTC)

fstab's /boot entry invalid for ESP
There's a "Configuring the /boot mountpoint" snippet in the "Alternative:_Using_genkernel" section which contains ext2 as a filesystem for /boot.

This part forgets to mention that ext2 is only valid for the non-UEFI setup and that vfat should be used for ESP.

Ajelinski (talk) 08:05, 29 June 2021 (UTC)

Skip "Installing the sources" section for distribution kernels ?
The instructions seem to imply that the first step to get a kernel is always to emerge gentoo-sources. I think if following the distribution kernel instructions, most of the sections above it can/should be skipped ? Kyoreln (talk) 14:28, 26 October 2021 (UTC)


 * I'll disagree here. If people fully read this, the introduction says the main way is manual config by installing gentoo-sources, but then also has 2 alternatives here which are listed later on. This is why it is a Handbook and not a walkthrough or quick guide.  It needs to be read and not just skip to commands. --Grknight (talk) 14:39, 11 January 2022 (UTC)

Mention license requirements for genkernel
In two sections, users are advised to use  to install. This is either done as part of installing initramfs as part of the manual build, or using genkernel to configure and build the full kernel.

When attempting to install,   will also attempt to install   as a dependency. When running the installation, the user may be notified that the package masked due to licensing. This causes the installation to fail.

!!! All ebuilds that could satisfy "sys-kernel/linux-firmware" have been masked. !!! One of the following masked packages is required to complete your request: - sys-kernel/linux-firmware-99999999::gentoo (masked by: || linux-fw-redistributable no-source-code license(s), missing keyword)

This can be solved by adding the  license group to   in the Portage configuration, or by adding a specific acceptance for that package. This is covered in the previous chapter for Installing the base system, including the reference to this specific package in the sample. But with the entire section marked as optional, I initially missed this, and it seems other users have too (Reddit example from April 2021).

If we might include a note or two on the Kernel installation chapter, advising users to be sure that they accept the necessary license for  (referencing the previous chapter) prior to attempting to install , I believe it would make for a smoother experience. Ssennettau (talk) 04:37, 19 December 2021 (UTC)


 * Mentioning the file is probably a better approach since its less heavy handed. This is something to be better addressed in the Handbook. I'll revisit this discussion when there's forward motion on this topic. --Maffblaster (talk) 18:32, 31 January 2022 (UTC)

Dial-up section can be removed
Zafarella (talk) 13:03, 11 January 2022 (UTC)


 * PPP is still very valuable to those who use PPPoE. Also, some real dial-up does exist so there doesn't seem to be a reason to remove anything here. --Grknight (talk) 14:32, 11 January 2022 (UTC)

`make localmodconfig` for simplifying configs
make localmodconfig seams could help lazy people like me to generate on loaded modules the flags. Does not work well though - tested, but seams very useful on getting working kernel. Docs = https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/README?id=refs/tags/v4.3.3#n205 it lists flags at least which is currently in use.

Prefix Kernel BreadCrumb for UEFI Support
under Enable support for UEFI

Prefix breadcrumbs with "Device Drivers".

existing:

Firmware Drivers ---> EFI (Extensible Firmware Interface) Support ---> <*> EFI Variable Support via sysfs should be:

Device Drivers Firmware Drivers ---> EFI (Extensible Firmware Interface) Support ---> <*> EFI Variable Support via sysfs

Jlpoole (talk) 18:26, 12 January 2022 (UTC)


 * Thank you! The suggestion has been merged. See Special:Diff/623256/1042620. --Maffblaster (talk) 21:23, 12 January 2022 (UTC)

IA32 Emulation moved
existing: Executable file formats / Emulations ---> [*] IA32 Emulation should be:

Binary Emulations ---> [*] IA32 Emulation pietinger


 * Fixed in this edit: Special:Diff/1042620/1044802. Thank you for the suggestion! --Maffblaster (talk) 19:19, 27 January 2022 (UTC)

I am so sorry for not have being exact. Please remove the tabulator spaces beause "Binary Emulations" is a item of the main menu and not a subitem of "Processor type and features". (shame about me) pietinger


 * Fixed. Thank you! --Maffblaster (talk) 21:05, 28 January 2022 (UTC)

Add Frambuffer discussion or pointer to article
I'm seeing a constant stream of people on the Gentoo forums saying "New kernel locks up on boot" that turn out to be a misconfigured or missing Framebuffer. There's no advice in the "Configuring the Linux kernel" article, but, at minimum for UEFI users and initramfs users, I think a small pointer to the wiki Framebuffer article would help.

Goverp (talk) 11:30, 13 February 2022 (UTC)


 * I've added the EFI framebuffer as a bare minimum to the Architecture specific kernel configuration section. If this can be improved further, I'd be open to it. --Grknight (talk) 17:40, 23 September 2022 (UTC)

This kernel will not boot
It is not only a missing link to framebuffer as Goverp suggested totally correct. Without a configuration for a HDD or NVMe a kernel having only this configuration will not boot, because module "ahci" is not enabled as default. We really should give a new Gentoo user two more links to: and direct to configure this also.
 * HDD
 * NVMe

pietinger 12:30, 8 March 2022 (UTC)


 * I agree, in the Handbook:AMD64/Installation/KernelInstallation/Kernel#Activating_required_options section, the options needed for NVMe should be included. I think also the option for USB4 should be added with the USB1,2,3 as they will be included in more and more systems in the future... but it's true that not including them at this step doesn't have so major consequences as NVMe stuff. Thanks --Pacho (talk) 09:50, 15 December 2022 (UTC)