User:Zulu Foxtrott/Parts/Installation/Kernel

{ {Handbook:Parts/TOC}}

Installing the sources
The core around which all Linux distributions are built is the Linux kernel. It is the layer between the user programs and the system hardware. Gentoo provides its users several possible kernel sources. A full listing with description is available at the Kernel overview page.

Downloading the sources
The recommended way to get the kernel sources is downloading them directly from upstream (the kernel developers themselves). Like with downloading the stage tarball, the only tool necessary is a web browser.

When installing kernel sources provided by Portage on a running Gentoo system, the package manager places them in the directory. Go to the directory that once the installation is finished and running on the target system will be found at :

Graphical browsers
In environments with fully graphical web browsers copy the kernel sources URL from. Right click on the big yellow button labeled "Latest Release" and featuring the current stable release's version number, then (Firefox) or  (Chromium) to copy the link to the clipboard, then paste the link to the  utility on the command-line to download the sources:

Command-line browsers
To download the kernel sources directly from a command line environment, use for example, the non-graphical, menu-driven browser.

To use an HTTP proxy with, pass on the URL with the  option:

Alternatively, use the (also non-graphical but not menu-driven) browser.

If a proxy needs to be defined, and it has not been done already, export the http_proxy and/or ftp_proxy variables:

Select the version number (or "Download" next to it) displayed below the line "Latest Release" and press to start the download.

Unpacking the sources
Create a directory on the storage device for the unpacked kernel sources:

Now unpack the downloaded kernel sources with into the newly created directory specified with the command line argument  :

This will install the Linux kernel sources under the path in a directory named "linux" followed by a version number. Change into that folder now:

TODO: reevaluate commented out parts

Now it is time to configure and compile the kernel sources.

Introduction
Manually configuring a kernel is often seen as the most difficult procedure a Linux user ever has to perform. Nothing is less true - after configuring a couple of kernels no-one even remembers that it was difficult ;)

However, one thing is true: it is vital to know the system when a kernel is configured manually.

Since these instructions are geared towards situations where it is usually impossible to gather information about the target system from the target system itself, it is necessary to rely on other sources. A good starting point is to search the Gentoo wiki, information provided here is naturally often superior to other sources as it is targeted specially at Gentoo installations. A second option is to have a look at the vendor's or manufacturer's documentation. Last but not least, it is of course also possible to ask the Internet in general.

Now go to the kernel source directory and execute. This will fire up menu-driven configuration screen.

The Linux kernel configuration has many, many sections. Let's first list some options that must be activated (otherwise Gentoo will not function, or not function properly without additional tweaks). We also have a Gentoo kernel configuration guide on the Gentoo wiki that might help out further.

Activating required options
Kernel drivers can be compiled as modules, that is they are only loaded upon request at runtime. Thus it is possible to have a smaller kernel, which may be of interest especially on embedded devices. However, using modules may have the effect of complicating the installation procedure. To that end and to ease the documentation effort, it is advised to disable loadable module support for now. To keep the kernel size small anyway, disable features that are not essential to get the target system up and running Gentoo. Drivers vital to booting the target system must always be compiled in the kernel and not as a module, otherwise the system will not be able to boot completely. Deselect Enable loadable module support ( CONFIG_MODULES ):

Select Maintain a devtmpfs file system to mount at /dev so that critical device files are already available early in the boot process ( CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT ):

It is essential to support the storage device of choice. Depending on its interface it may be necessary to select additional hardware specific drivers, for instance in case of MMC and SD cards. Of course it's always possible to simply select all offered options in the relevant submenus and optimize the kernel once the installation is running on the target system.

To add general support for MMC and SD cards, select MMC/SD/SDIO card support and the MMC block device driver and for SD cards, additionally activate Secure Digital Host Controller Interface support ( CONFIG_MMC, CONFIG_MMC_BLOCK , CONFIG_MMC_SDHCI ):

Don't forget to include the hardware specific drivers.

If Gentoo is supposed to run from a USB stick, verify SCSI disk support and USB Mass Storage support have been activated ( CONFIG_BLK_DEV_SD, CONFIG_USB_SUPPORT , CONFIG_USB_XHCI_HCD , CONFIG_USB_EHCI_HCD , CONFIG_USB_OHCI_HCD and CONFIG_USB_STORAGE ):

Supporting other storage devices (for example NVMe or SATA drives) will require selecting additional sets of options.

Now go to File Systems and select support for at least all the filesystems applied to the partitions on the storage device. Do not compile the file system that is used for the root filesystem as module, otherwise the Gentoo system will not be able to mount the partition. Also select Virtual memory and /proc file system. Select one or more of the following options as needed by the system ( CONFIG_EXT2_FS, CONFIG_EXT3_FS , CONFIG_EXT4_FS , CONFIG_MSDOS_FS , CONFIG_VFAT_FS , CONFIG_PROC_FS , and CONFIG_TMPFS ):

Most systems also have multiple cores at their disposal, so it is important to activate Symmetric multi-processing support ( CONFIG_SMP ):

If any USB input devices (like keyboard or mouse) or other USB devices will be used, do not forget to enable those as well ( CONFIG_HID_GENERIC and CONFIG_USB_HID, CONFIG_USB_SUPPORT , CONFIG_USB_XHCI_HCD , CONFIG_USB_EHCI_HCD , CONFIG_USB_OHCI_HCD ):

For graphics output, enable the hardware specific drivers. In many cases it is also necessary to select Enable legacy fbdev support for your modesetting driver ( CONFIG_DRM_FBDEV_EMULATION ):

Do not forget to include support in the kernel for the network (Ethernet or wireless) adapter.

Also select System V IPC, Control Group support, UTS namespace, IPC namespace, PID namespace and Network namespace, which are features required for Portage to work ( CONFIG_SYSVIPC, CONFIG_CGROUPS , CONFIG_UTS_NS , CONFIG_IPC_NS , CONFIG_PID_NS , and CONFIG_NET_NS ):

{ {Handbook:/Blocks/Kernel}}

Optional: Activating required options for LUKS encryption
If the main partition has been encrypted, an initial RAM file system (initramfs) needs to be created. It provides a minimal root filesystem and some tools (applications) to the kernel and takes care of making the "real" root filesystem accessible (it unlocks the encrypted partition). To keep its size small, it can be compressed. In this document gzip will be used as an example.

To have the kernel support a gzip compressed initramfs select Initial RAM filesystem and RAM disk (initramfs/initrd) support and ''Support initial ramdisk/ramfs compressed using gzip"" ( CONFIG_BLK_DEV_INITRD and CONFIG_RD_GZIP ):

As LUKS relies on the dm-crypt disk encryption system, which is part of the kernel's device mapper subsystem, also select Device mapper support and Crypt target support ( CONFIG_BLK_DEV_DM and CONFIG_DM_CRYPT ):

Last but not least, the kernel needs built-in support for the ciphers, keys and hashes used to encrypt the storage device. ( CONFIG_CRYPTO_XTS, CONFIG_CRYPTO_SHA512 , CONFIG_CRYPTO_AES , CONFIG_CRYPTO_USER_API_HASH and CONFIG_CRYPTO_USER_API_SKCIPHER )

Do not skip the following section and build an initramfs now.

Optional: Building an initramfs
If the main partition has been encrypted, building an initial RAM file system (initramfs) is required.

Another common reason for building an initramfs is when important file system locations (like or ) are on separate partitions.

As outlined in the section before an initramfs provides a minimal root filesystem and some tools (applications) to the kernel. It usually takes care of making the "real" root filesystem accessible. Depending on the tools included, different tasks can be performed. Thus it's possible to configure it not only to mount separate partitions or decrypt devices but also to do something else.

First, create a directory for the initramfs:

Creating the intiramfs filesystem structure
Create a minimal root filesystem structure in that directory, using with the command line argument   to allow that all necessary parent directories are created as well:

TODO: compare

Creating necessary device nodes
The initramfs' directory needs to be populated with the necessary device nodes. Device nodes are block or character special files - files that can generate or receive data. They can be created with the command. The argument  followed by the file permissions allows to set these correctly (in the example the numeric notation is used). Following that is the name of the new device node before its type ( for character devices and   for block devices) is defined. This is concluded by the major and minor device numbers. (The major number identifies the device type and thus the driver and the minor number identifies the device served by the driver.)

Create the required character device nodes:

After creating the tty device node, its group ownership should be changed:

This is not necessary for the console device node, but its file permissions are more restricted:

Finally create the required block device node with the correct permissions and adjust the group ownership as recommended:

Now that all necessary device nodes have been created, it is time to add some tools so the initramfs can actually serve its purpose.

Adding tools (applications)
Any application that needs to be executed before the "real" root filesystem is available to the kernel must be present on the initramfs. In the best case these tools are included in the stage tarball that has been downloaded and unpacked earlier in the installation process. Sometimes, however, when this is not the case, it may become necessary to be creative. If the host system's and the target system's architecture are identical they could be installed on the host system and copied from there, for instance. In any case the simplest approach is to use only statically linked binaries, which means only one file will have to be copied over to the initramfs instead of many files to different directories of the initramfs.

busybox cryptsetup

script
kernel compilation still difficult?

The initramfs will be stored in. The resulting file can be found by simply listing the files starting with initramfs:

{ {Handbook:Parts/Navigator|Prev=Handbook:/Installation/Base|Next=Handbook:/Installation/System}}