User:Pietinger/Tutorials/Manual kernel configuration

From Gentoo Wiki
Jump to:navigation Jump to:search
Even though this page is in the user namespace, corrections and additions are much appreciated! This is simply wiki policy, this page can be moved to the main wiki as soon as it achieves critical mass more.

Here I gather all informations and links I miss in our AMD64 Handbook.

Tutorial: Manual kernel configuration

This tutorial gathers all links and informations needed for a manual kernel configuration. Only our Gentoo default sources will be used.

I present a link here at this prominent place because in my opinion every linux user should know this:

It is named: "Demystifying the Linux kernel security process" from Greg KH. If you dont know Greg KH then read: [[1]] ;-)

What you have to know / What you should read


Many options in your 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. My recommendation for later: Look into every <Help> of an option you want to enable or disable and read not only the help text ... moreover read also all information in the last section, where you can find something like "Selects:" and/or "Selected by:" and/or "Depends on:". These will show you the dependencies to (or from) other modules.

You can search for kernel modules in "make menuconfig" by pressing / Typing a leading "CONFIG_" is not necessary.

You must enable all modules which kernel needs to find its root partition static <*> into your kernel and not as <M>odule !

Never edit .config

I quote from this thread: [2]

"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 informations

If you have never done a manual kernel configuration you really should read all these before starting:

Before you start

1. Choose which kernel version you want and install it. This may help you: User:Pietinger/Tutorials/Selecting_a_convenient_kernel_version

2. Gather some informations: Boot with Handbook:AMD64/Installation/Media#Minimal_installation_CD, or simply with an unchanged Gentoo dist-kernel if you have already installed it, and do (as user 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 - except above.

root #dmesg | grep firmware

Notice all firmware files (with directory).

For an INTEL or AMD system ask also:

root #dmesg | grep stepping

Notice family, model and stepping.


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 our AMD64 handbook.

What you should configure at minimum

Basic Settings (Must have)

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. Now 6.6 is stable and I did a new page (because it would be too huge here):


Archive 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:

Sound and others

This should be done also:

Optional settings

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 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.

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 defconfig
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:

  • 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 does a "make oldconfig" ?

This will do three things:

1. Remove elements that are not anymore in the new kernel (if kernel developers have removed an existant option in the new kernel).

2. Keep the settings that are valid for the new kernel (takeover).

3. Ask you 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 you need. You can take this default simply with <return>.

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


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:

FILE /usr/src/linux/.config
CONFIG_PNP_DEBUG_MESSAGES=y  (default in 6.1)
CONFIG_DEBUG_INFO_NONE=y  (default in 6.1)
CONFIG_DEBUG_STACK_USAGE (default in 6.6 but unnecessary => disable it)
CONFIG_DEBUG_PREEMPT=y  (default in 6.1) (no default in 6.6 anymore => disable it ;-)
CONFIG_DEBUG_BUGVERBOSE=y (default in 6.1)

Two more options depends on:

FILE /usr/src/linux/.config
# Enabled by selecting CONFIG_EXPERT

And if you hopefully harden your kernel with KSPP you will get automatically these (example X86_64 system):

FILE /usr/src/linux/.config
# KSPP: Allow allocator validation checking to be enabled (see "slub_debug=P" below).

# KSPP: Report any dangerous memory permissions (not available on all archs).

# KSPP: Perform additional validation of various commonly targeted structures.

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:

FILE /usr/src/linux/.config

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: [[4]]

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:

Useful links

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.