User:Immolo/Sandbox/Manual kernel
For users that wish to create their own kernel without the help of external tools highlighted in the Handbook.
Tutorial: Manual kernel configuration
This tutorial gathers all links and informations needed for a manual kernel configuration.
Only our default sys-kernel/gentoo-sources will be used.
An interesting video here that Linux user should know about: https://www.youtube.com/watch?v=Rg_VPMT0XXw by Greg KH.
Foreword
A first-time manual configuration of the kernel is not done in a few minutes. If you follow this advice to read the help, it may take a few hours. But this effort is unique. Later a user will apply new kernel versions with make oldconfig, which is done in a few minutes (when switching to a new major version), or even instantaneously (if only changing the minor version).
Do not try to configure a “perfect” kernel at the first attempt. This will hardly be possible and is not even necessary. The most important thing to start with is that it boots at all. If the sound doesn't work yet, that's not a problem - you can make up for it later. The sound is also the most common problem with a kernel configuration; if it doesn't work straight away you're in good company and don't have to be frustrated; so far we've managed to get every exotic part to work. The more often a user visits the kernel configuration, the greater understanding of where, which parts and how they belong together.
One more word about security: The less software you use, the fewer potential attack surfaces a system offers. This also applies to the kernel, which we therefore want to keep as lean as possible. This means: If you are unsure whether you need a parameter, it is better to leave it out. If something is missing, the user will notice immediately - because something will not work. But if the user include something that will never be needed again, the user won't even notice it. So: If in doubt, leave it out for now or only configure it as module <M> (if this is possible).
The above statement is part of a process towards security and not always the best option.
Big request: First read this article completely before doing anything. Then start from the beginning and look for all the links. Then read these linked articles. Only then really start with the configuration.
Precursors
Basics
The AMD64 Handbook (currently) recommends make nconfig for kernel configuration. This article recommend the old make menuconfig, as there are more options here, e.g. display invisible options with z.
It is possible to search for kernel modules in make menuconfig by pressing /. Typing a leading "CONFIG_" is not necessary.
The user must enable all modules which kernel needs to find its root partition static <*> into the kernel and not as <M>odule !
Many options in a kernel configuration depends on other options. Many options selects one or more other options. Sometimes a option is not visible whilst others are not enabled. This article recommends for later: Look into every <Help> of an option needed to enable or disable and read not only the help text ... moreover read also all information in the last section, where more information can find something like "Selects:" and/or "Selected by:" and/or "Depends on:". These will show the dependencies to (or from) other modules. One example:
Cannot deactivate an option
If there is a want to disable an option marked with -*- but make menuconfig does not allow it.
Remember it is possible to look in the <Help> to find the reason for this there. An example:
[*] Networking support --->
Networking options --->
-*- The IPv6 protocol --->
The <Help> says:
Selected by [y]: - GENTOO_LINUX_INIT_SYSTEMD [=y] && GENTOO_LINUX [=y] && GENTOO_LINUX_UDEV [=y]
Look in the <Help> of GENTOO_LINUX_INIT_SYSTEMD:
Gentoo Linux --->
Support for init systems, system and service managers --->
[*] systemd
... to find the resaon:
Selects: AUTOFS_FS [=y] && ... IPV6 [=y]
If a user needs systemd and doesn't want IPv6 - what could be done? It's quite simple: First, disable GENTOO_LINUX_INIT_SYSTEMD and can then also disable IPv6 ... but be careful: Now there is a need to enable everything else that GENTOO_LINUX_INIT_SYSTEMD has enabled itself (see "Selects:"). An easier way to disable IPv6 is to use a kernel command line parameter: User:Pietinger/Tutorials/Kernel_Commandline_Parameter
Never edit .config
Quoting from this thread:
Horrible things happen if you use a text editor on the kernel .config file.
If you are lucky, you will get a kernel that won't build. If not, it may be broken in ways that nobody has ever seen before.
Use menuconfig and its search. Press / If the symbol you want is not found, press the 'z' key to toggle the display of hidden symbols. Search again.
The search will find it but you still can't select it. Read the help on the menu option. Pay attention to the Depends on: That boolean expression must be true before the item can be selected. Select other things so that your symbol can be selected.
Read the Selects: too. Now ask yourself if you would have got that right with your text editor?
The usual advice to someone who has used a text editor on the .config file is to throw it away and start it again.
More information
More information for users that have never done a manual kernel configuration that should be read before starting:
- PC_Boot_Process
- Kernel/Gentoo_Kernel_Configuration_Guide
- Kernel/Configuration
- Short Explanation of which kernel modules are needed for a certain harddisk: [1]
Before you start
1. Choose which kernel version is desired. This may be of assistance: User:Immolo/Sanbox/Manual_kernel/Selecting_a_convenient_kernel_version
2. Gather some informations: Boot with Handbook:AMD64/Installation/Media (*), or simply with an unchanged Gentoo distribution-kernel if it is already installed it, and do (as root):
root #
lspci -nnk
Notice all modules from line Kernel driver in use: XXXX
. Maybe read beforehand: User:Pietinger/Overview_of_System_Information#lspci_-nnk
root #
lsmod | more
Notice all modules.
root #
dmesg | grep firmware
Notice all firmware files (with directory).
For an Intel or AMD systems, also run:
root #
dmesg | grep stepping
Notice family, model and stepping.
Gentoo Linux --->
[*] Print firmware information that the kernel attempts to load
BIOS
For current reasons ... and because it is unfortunately not mentioned anywhere: No Linux likes "Fast Boot" activated in the BIOS ... check it and deactivate it. Other settings such as SecureBoot (must also be disabled) or CSM mode (also off) have already been mentioned in the AMD64 handbook.
Is a "make defconfig" required before starting?
The Kconfig system of the kernel is a bit tricky. There are dependencies and also defaults. But as soon as a created configuration is saved, there is no way back. What is meant: If a kernel module (A) requires another (B) and therefore selects it, B is automatically enabled as soon as A is enabled. If it is saved now, A and B are saved as enabled. Upon returning to the configuration and deactivating A again, B will NOT be disabled automatically. B REMAINS activated because it was saved as such. This behavior means that there is a clear difference whether a “make menuconfig” is run in a directory without an existing .config file (= freshly emerged gentoo-sources), or whether a “make menuconfig” is run after a “make defconfig” (because the "make defconfig" creates a .config file and already saves something). The same applies to all “defaults” specified by Kconfig. However, once saved, the defaults are no longer used. This is also explained in a forum thread. So if a closer look is desired, refer to this forum post.
The answer to the above question is therefore a definite NO.
On the contrary: A “make menuconfig” with a freshly emerged gentoo-sources is advantageous.
For example: If WLAN is switched off, all (now no longer) required crypto modules are automatically deactivated. This is no longer possible after a “make defconfig”, because the Crypto module is then already saved as enabled. This behavior is also used here to configure something that is not actually intended: User:Pietinger/Tutorials/Kernel_Hardening_with_KSPP
Introduction
If this is the first time running make menuconfig it can be confusing what do and where to start. Here are some general words about the main menu (just read it - don't start yet):
The last line Gentoo Linux ---> exists only in gentoo-sources. If the system has other sources (e.g. vanilla) some options won't match. If using OpenRC as init system there is nothing to do here. If using systemd. then enable one option - which is usually already enabled by systemd-stage3. So we do only a check here if it is correct:
Gentoo Linux --->
Support for init systems, system and service managers --->
[*] OpenRC, runit and other script based systems and managers
[ ] systemd
Although our AMD64 Handbook says: “It does not hurt to have support for both init systems enabled.” I do not recommend enabling "systemd" if you have an OpenRC system: All the really important ones are already activated by default, or we will activate them here, and we don't want the additional ones (BPF_SYSCALL, CGROUP_BPF).
In the next last option Kernel hacking ---> this really should only change something with specific instructions !
Also, leave Library routines ---> because all necessary modules here will be selected (=enabled) automatically by other options - with one exception: Here you can change the selected font. At the moment you are not able to do this because one other option is not enabled. If you press z in this menu you can see this is disabled at the moment:
Library routines --->
- - Select compiled-in fonts
Now look into the help of this option and you will see why it is not possible:
Depends on: FONT_SUPPORT [=y] && (FRAMEBUFFER_CONSOLE [=n] || STI_CONSOLE [=n])
Now leave the help, press z again (toggle function) and exit this menu. Yes, we really need FRAMEBUFFER_CONSOLE - it is a MUST HAVE - and we do this in the next chapter.
The same is true for Cryptographic API --->. Usually all necessary modules here will be selected automatically by enabling other kernel (*) modules (with one exception: dmcrypt; but you will find instructions in every description for dmcrypt). At the moment many options are enabled because some other options are still enabled (e.g. WLAN, IPSec). If we disable WLAN or IPv6 (or both) we can disable also some of these cryptographics modules later.
(*) This is not true for user applications. If an user application - like iwd - needs some crypto modules you will always need a description which crypto modules you have to enable. In most cases, at least this is required:
-*- Cryptographic API --->
Crypto core or helper --->
-*- Cryptographic algorithm manager
<*> Userspace cryptographic algorithm configuration
Userspace interface --->
<*> Hash algorithms
<*> Symmetric key cipher algorithms
[ ] Obsolete cryptographic algorithms
One option we have in the main menu you should think about at last when all is done: [*] Enable loadable module support ---> Why ? I recommend to configure all necessary modules static into the kernel - because you will need your ethernet and graphics module always ... If we do this then we dont need a loadable module support anymore and we can disable this ... and have now a monolithic kernel. Why we want do this ? Because it is more secure. Also KSPP recommends to disable module support or work with signed modules. But for the moment we dont change it and you can think about later.
We will get to know all the other menu items in the next chapter.
Configuration
Basic Settings
Start with our Handbook:AMD64/Installation/Kernel#Alternative:_Manual_configuration (just read it). I am missing some important options. In the past I had here some options for kernel version 5.15. I have separated it out so that I can differentiate between the latest stable (*) and the latest LTS kernel (* stable in the sense of the Linux kernel developers - not in the sense of Gentoo; in Gentoo the latest LTS kernel is labeled as stable).
Latest LTS kernel: User:Pietinger/Tutorials/Manual_Configuring_Kernel_Version_6.6
Latest stable kernel (currently 6.11): User:Pietinger/Experimental/Manual_Configuring_Current_Kernel
( Outdated link: User:Pietinger/Tutorials/Manual_Configuring_Kernel_Version_6.1 )
After this come back to this page, because you have to do a little bit more. In all Links you will get now, you will need only the chapter Kernel Configuration:
Graphics adapter
Choose from these links:
If you have a kernel of version 6.10 or higher, note that many settings for the graphics can now be found here (in DRM):
Device Drivers --->
Graphics support --->
<*> Direct Rendering Manager (XFree86 4.1.0 and higher DRI support) --->
...
Sound and others
Although we already have a wiki article about ALSA, I would like to present the complete menu here to get a minimal sound configuration. If your sound works with it, no further steps are necessary. If not, you have a system that needs either USB support or even ALSA for SoC audio support. Here you will need your “lsmod” query to load additional sound modules.
Device Drivers --->
<*> Sound card support --->
<*> Advanced Linux Sound Architecture --->
--- Advanced Linux Sound Architecture
[ ] Enable OSS Emulation
[*] PCM timer interface
<*> HR-timer backend support
# You need UDEV for this. Read the <Help>
-*- Dynamic device file minor numbers
(32) Max number of sound cards
[ ] Support old ALSA API
[*] Sound Proc FS Support
[*] Verbose procfs contents
[ ] Verbose printk
[*] Fast lookup of control elements
# Not absolutely necessary - there are some useful messages in “dmesg” - your decision
[*] Debug
[ ] More verbose debug
[ ] Enable PCM ring buffer overrun/underrun debugging
[ ] Validate input data to control API
[ ] Enable debugging feature for control API
<*> Sequencer support
<*> Sequencer dummy client
[*] Use HR-timer as default sequencer timer
[ ] Support for UMP events
[ ] Generic sound devices ----
[*] PCI sound devices --->
HD-Audio --->
<*> HD Audio PCI
[*] Build hwdep interface for HD-audio driver
[*] Allow dynamic codec reconfiguration
<*> Build Realtek HD-audio codec support
# If you want to use your speakers in the monitor connected via HDMI or DisplayPort. This selects "Dynamic device file minor numbers"
<*> Build HDMI/DisplayPort HD-audio codec support
-*- Enable generic HD-audio codec parser
(0) Default time-out for HD-audio power-save mode
[ ] USB sound devices ----
# If you have already deactivated PCMCIA, this option will no longer appear
[ ] PCMCIA sound devices ----
< > ALSA for SoC audio support ----
[ ] X86 sound devices ----
# if you have already deactivated every VRTIO module, this option will no longer appear
< > Virtio sound driver
This should be done also:
Optional settings
- CDROM
- Webcams
- Motion
- NTFS
- KDE Vaults needs FUSE: Encfs
- Dolphin (from KDE) needs also FUSE for drag-and-drop
- USB_Power_Saving
- USB_to_serial_adapter
- Wireless Local Area Network (WLAN): Wi-Fi / Iwd / Iwlwifi
- Bluetooth
- Zswap
- I dont recommend to use this: Magic_SysRq
At last you can check all other modules you have in your lists from lspci -k and lsmod by searching with /
And last but not least, you should read this:
Driver needs Firmware
Some kernel modules need firmware (mostly Graphics adapter, WLAN and some Ethernet). If you use one of these kernel modules you should emerge Linux_firmware#Emerge. Now you have two options for this module:
a) If you have configured your module as <M>odule, then the kernel is able to load firmware for this module at boot-time from /lib/firmware, because all <M>odules will be initalised after kernel has access to its root partition.
b) If you have configured your module static <*> into your kernel, then you must do a little bit more. These modules will be initalised before kernel has access to its root partition and therefore is not able to load firmware from /lib/firmware.
You would get an error message in your "dmesg" saying Direct firmware load for xxxx/xxx failed with error -2
. Therefore you must compile all needed firmware also into your kernel (example):
Device Drivers --->
Generic Driver Options --->
Firmware Loader --->
[*] Firmware loading facility
(i915/skl_dmc_ver1_27.bin intel-ucode/06-5e-03) Build named firmware blobs into the kernel binary
With these settings you will copy these firmware files "INTO" your kernel (when you compile your kernel with "make") and now the kernel is able to "load" these firmware files "from itself" without needing access to /lib/firmware at boot-time.
Yes, it is the same place where you can also define the microcode blob; if more than one firmware blobs must be loaded you separate them with a space.
Every Wiki article recommends to use option (a) because it is very easy. Option (b) is necessary if you want to build a monolithic kernel without module support, or if you have other reasons to build a module (which needs firmware) static into your kernel.
In some wiki pages you will find examples of necessary firmware files you need when using option (b), like this example:
amdgpu/oland_{uvd,smc,rlc,pfp,me,mc,ce}.bin
DONT try to put this into your path; it will not work because you can add only single files; many readers of the page AMDGPU dont notice the little sentence: "Use echo to expand the filenames" ... yes, you can only add:
amdgpu/oland_uvd.bin amdgpu/oland_smc.bin amdgpu/oland_rlc.bin amdgpu/oland_pfp.bin amdgpu/oland_me.bin amdgpu/oland_mc.bin amdgpu/oland_ce.bin
If you use option (b) you cannot use compressed firmware files. Read the <Help> of:
Device Drivers --->
Generic Driver Options --->
Firmware Loader --->
[ ] Enable compressed firmware support
It says quite clearly: Compressed firmware support does not apply to firmware images that are built into the kernel image (CONFIG_EXTRA_FIRMWARE).
This also means that you must NOT emerge the package "linux-firmware" with the use-flags for compression (compress-xz, compress-zstd) !
Starting with a clean environment
If you have done already some configurations and want to start from beginning you can clean up all with
root #
cd /usr/src/linux
root #
make distclean
root #
make menuconfig
The first command (distclean) deletes all old data - also your .config file !
Cheat Sheets
These are only valid for a completely (*) manually configured kernel according to our Handbook:AMD64/Installation/Kernel#Alternative:_Manual_configuration and you are using grub as bootmanager.
(*) means: You are not using an intramfs from genkernel or dracut !
Mounting (and unmounting) the boot partition is only necessary if you have an old installation where you mount your ESP to /boot instead of /efi. If you have questions about this then please read: https://forums.gentoo.org/viewtopic-t-1165115-highlight-.html
- Updating to a new kernel version:
root #
emerge -1uvDp gentoo-sources
root #
( mount /boot )
root #
# go into the directory of the new kernel:
root #
cd /usr/src/linux-X.Y.Z-gentoo
root #
cp /usr/src/linux/.config .
root #
make oldconfig
root #
# For X use nr. of your CPU cores:
root #
make -j X
root #
make install
root #
make modules_install
root #
# Maybe you want to backup your configuration. I do this into:
root #
cp .config /etc/MY/config-X-Y-Z
root #
grub-mkconfig -o /boot/grub/grub.cfg
root #
eselect kernel list
root #
eselect kernel set X
root #
( umount /boot )
root #
reboot
- Changing the configuration of your used kernel:
root #
( mount /boot )
root #
cd /usr/src/linux
root #
make menuconfig
root #
make -j X
root #
make install
root #
make modules_install
root #
cp .config /etc/MY/config-X-Y-Z-revA
root #
grub-mkconfig -o /boot/grub/grub.cfg
root #
( umount /boot )
root #
reboot
If you ever have problems with a make install, then read Installkernel (because this package creates some routines that are then started by a make install"), OR simply copy the kernel yourself to /boot (=instead using make install):
root #
cp arch/x86/boot/bzImage /boot/vmlinuz-X.Y.Z-gentoo
(Yes, actually you don't need the *map* and config* file in /boot).
What is "make oldconfig" ?
This will do three things:
1. Remove elements that are not any more in the new kernel (i.e. kernel developers have removed an option in the new kernel).
2. Keep the settings that are valid for the new kernel (takeover).
3. Ask about all the new settings (only it there are new options; seldom with a change of the minor version; almost always with a new major version).
The prompt for new settings will show y/m/n/?
Yes makes the option built in, M makes it a module, No leaves it out and ? shows the help.
Not all four options are shown every time. If an option cannot be a module then of course M is missing.
One of y/n/m will be a capital letter. This is the default, it may or may not be what the system needs. If you are unsure, accept the default with <Return> or read the corresponding articles in: User:Pietinger/Experimental.
Kconfig / KSPP ?
View the content of /usr/src/linux/distro/Kconfig ... and examine if you have really enabled some security options. Take a look into User:Pietinger/Tutorials/Kernel_Hardening_with_KSPP
CONFIG_DEBUG ?
If you do this search you will see many lines:
root #
grep DEBUG /usr/src/linux/.config
Most of them are disabled with # CONFIG_* is not set - some are enabled. If experienced users tell you "dont enable debugging", they are usually correct. But not in every case, because for some settings you dont have an influence like all CONFIG_ARCH_* and CONFIG_HAVE_*. An Intel X86_64 system gives you these enabled:
CONFIG_X86_DEBUGCTLMSR=y (6.1)
CONFIG_ARCH_SUPPORTS_DEBUG_PAGEALLOC=y
CONFIG_PNP_DEBUG_MESSAGES=y (default in 6.1)
CONFIG_DEBUG_INFO_NONE=y (default in 6.1)
CONFIG_ARCH_HAS_DEBUG_WX=y
CONFIG_HAVE_DEBUG_KMEMLEAK=y
CONFIG_DEBUG_STACK_USAGE (default in 6.6 but unnecessary => disable it)
CONFIG_ARCH_HAS_DEBUG_VM_PGTABLE=y
CONFIG_ARCH_HAS_DEBUG_VIRTUAL=y (6.1)
CONFIG_DEBUG_PREEMPT=y (default in 6.1) (no default in 6.6 anymore => disable it ;-)
CONFIG_LOCK_DEBUGGING_SUPPORT=y (default in 6.1)
CONFIG_DEBUG_BUGVERBOSE=y (default in 6.1)
Two more options depends on:
# Enabled by selecting CONFIG_EXPERT
CONFIG_DEBUG_KERNEL=y
CONFIG_DEBUG_MISC=y
And if you hopefully harden your kernel with KSPP you will get automatically these (example X86_64 system):
# KSPP: Allow allocator validation checking to be enabled (see "slub_debug=P" below).
CONFIG_SLUB_DEBUG=y
# KSPP: Report any dangerous memory permissions (not available on all archs).
CONFIG_DEBUG_WX=y
# KSPP: Perform additional validation of various commonly targeted structures.
CONFIG_DEBUG_VIRTUAL=y
CONFIG_DEBUG_LIST=y
CONFIG_DEBUG_SG=y
CONFIG_DEBUG_NOTIFIERS=y
CONFIG_DEBUG_CREDENTIALS=y
Now you have 13 (20 with 6.1) (19 with 6.6) DEBUG-options enabled and this is completely fine ! If you find any other lines with enabled DEBUG you should ask yourself why you have enabled them. Okay, enabling CONFIG_SND_DEBUG doesnt hurt ... you will get more informations about your sound. But all others should be enabled only for special investigations (== if you know what you are doing). A really bad example (because of security risk) is:
CONFIG_DEBUG_FS=y
It is only necessary if you want do special operations, e.g. using PowerTOP to examine your machine. Dont worry if you get messages about a missing DEBUG_FS in your dmesg ... I have also some:
intel-lpss 0000:00:15.0: Failed to create debugfs entries
Comparison between two kernel configuration files
Of course you can use "diff" or any other grapical tool like "kompare" (from KDE), but a really great tool you will find here: [[2]]
Compare the log of your system startup
You can do this by using the -t parameter with "dmesg" when redirecting the output of "dmesg" to a file. Example:
root #
dmesg -t > kernel-log-6.1.46
This way no timestamps are logged at the beginning of the line and you can compare your different logs of a system boot. Use this also when you change BIOS options (just try to disable or enable VT-D and check the changes in the log). I found this simple and ingenious approach here: https://forums.gentoo.org/viewtopic-p-8517143.html#8517143
Useful links
- https://www.kernel.org/doc/html/latest/
- https://kernelnewbies.org/LinuxChanges
- https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
- https://lwn.net/Kernel/Index/#Releases
- https://lore.kernel.org/linux-cve-announce/
This is my second try for creating a wiki article. Maybe some formatting is wrong. Because it is a tutorial and not a reference guide I ignored the standard of not writing in first or second person. Yes, my english is very poor.