User:Zulu Foxtrott/Parts/Installation/Kernel

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

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 temporary root filesystem and the tools necessary 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 )

Optional: Building an initramfs
In certain cases it is necessary to build an initramfs - an initial ram-based file system. The most common reason is when important file system locations (like or ) are on separate partitions. With an initramfs, these partitions can be mounted using the tools available inside the initramfs.

Without an initramfs, there is a huge risk that the system will not boot up properly as the tools that are responsible for mounting the file systems need information that resides on those file systems. An initramfs will pull in the necessary files into an archive which is used right after the kernel boots, but before the control is handed over to the init tool. Scripts on the initramfs will then make sure that the partitions are properly mounted before the system continues booting.

To install an initramfs, install first, then have it generate an initramfs:

In order to enable specific support in the initramfs, such as LVM or RAID, add in the appropriate options to. See for more information. In the next example support is enabled for LVM and software RAID :

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