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 /usr/src directory. Go to the directory that once the installation is finished and running on the target system will be found at /usr/src:

root #cd /mnt/gentoo/usr/src

Graphical browsers

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

root #wget <PASTED_KERNELSOURCES_URL>

Command-line browsers

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

root #links https://www.kernel.org

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

root #links -http-proxy proxy.server.com:8080 https://www.kernel.org

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

root #lynx https://www.kernel.org

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

root #export http_proxy="http://proxy.server.com:port"

root #export ftp_proxy="http://proxy.server.com:port"

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

Unpacking the sources

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

root #mkdir /mnt/gentoo/usr/src/upstream-sources

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

root #tar xpvf linux-*.tar.xz -C /mnt/gentoo/usr/src/upstream-sources

This will install the Linux kernel sources under the path /mnt/gentoo/usr/src/upstream-sources in a directory named "linux" followed by a version number. Change into that folder now:

root #cd /mnt/gentoo/usr/src/upstream-sources/linux-*

TODO: reevaluate commented out parts

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

Manual configuration

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 make menuconfig. This will fire up menu-driven configuration screen.

root #make menuconfig

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

KERNEL Disabling loadable module support

[ ] Enable loadable module support  --->

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

KERNEL Enabling devtmpfs support

Device Drivers --->
  Generic Driver Options --->
    [*] Maintain a devtmpfs filesystem to mount at /dev
    [*]   Automount devtmpfs at /dev, after the kernel mounted the rootfs

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

KERNEL Enabling MMC and SD card support

Device Drivers --->
  <*> MMC/SD/SDIO card support  --->
      <*>   MMC block device driver
      <*>   Secure Digital Host Controller Interface support

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

KERNEL Enabling USB mass storage support

Device Drivers --->
  SCSI device support  --->
      <*> SCSI disk support
  [*] USB support  --->
      <*>   xHCI HCD (USB 3.0) support
      <*>   EHCI HCD (USB 2.0) support
      <*>   OHCI HCD (USB 1.1) support
      <*>   USB Mass Storage support

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

KERNEL Selecting necessary file systems

File systems --->
  <*> Second extended fs support
  <*> The Extended 3 (ext3) filesystem
  <*> The Extended 4 (ext4) filesystem
  <*> Reiserfs support
  <*> JFS filesystem support
  <*> XFS filesystem support
  <*> Btrfs filesystem support
  DOS/FAT/NT Filesystems  --->
    <*> MSDOS fs support
    <*> VFAT (Windows-95) fs support
 
Pseudo Filesystems --->
    [*] /proc file system support
    [*] Tmpfs virtual memory file system support (former shm fs)

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

KERNEL Activating SMP support

Processor type and features  --->
  [*] Symmetric multi-processing support

Note
In multi-core systems, each core counts as one processor.

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

KERNEL Activating USB support for input devices

Device Drivers --->
  HID support  --->
    -*- HID bus support
    <*>   Generic HID driver
    [*]   Battery level reporting for HID devices
      USB HID support  --->
        <*> USB HID transport layer
  [*] USB support  --->
    <*>   xHCI HCD (USB 3.0) support
    <*>   EHCI HCD (USB 2.0) support
    <*>   OHCI HCD (USB 1.1) support

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

KERNEL Enabling fbdev emulation

Device Drivers --->
  Graphics support  --->
    [*] Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)  --->
      [*]   Enable legacy fbdev support for your modesetting driver

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

KERNEL Enabling features required for Portage

General setup --->
  [*] System V IPC
  [*] Control Group support
  [*] Namespaces support --->
      [*] UTS namespace
      [*] IPC namespace
      [*] PID namespace
      [*] Network namespace

{{Handbook:Zulu Foxtrott/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):

KERNEL Enabling initramfs support

General setup  --->
    [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
    [*]   Support initial ramdisk/ramfs compressed using 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):

KERNEL Enabling device mapper and crypt target

[*] Enable loadable module support
Device Drivers --->
    [*] Multiple devices driver support (RAID and LVM) --->
        <*> Device mapper support
        <*>   Crypt target support

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)

KERNEL Enabling cryptographic API functions

[*] Cryptographic API --->
    <*> XTS support
    <*> SHA384 and SHA512 digest algorithms
    <*> AES cipher algorithms
    <*> User-space interface for hash algorithms
    <*> User-space interface for symmetric key cipher algorithms

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 /usr/ or /var/) 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:

root #mkdir /mnt/gentoo/usr/src/initramfs

Creating the intiramfs filesystem structure

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

TODO: compare

root #mkdir -p /mnt/gentoo/usr/src/initramfs/{bin,dev,etc,lib,lib64,mnt/root,proc,root,run,sbin,sys}

Creating necessary device nodes

The initramfs' /dev 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 mknod command. The argument -m 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 (c for character devices and b 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:

root #mknod -m 666 /mnt/gentoo/usr/src/initramfs/dev/null c 1 3

root #mknod -m 666 /mnt/gentoo/usr/src/initramfs/dev/random c 1 8

root #mknod -m 666 /mnt/gentoo/usr/src/initramfs/dev/urandom c 1 9

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

root #mknod -m 666 /mnt/gentoo/usr/src/initramfs/dev/tty c 5 0

root #chgrp tty /mnt/gentoo/usr/src/initramfs/dev/tty

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

root #mknod -m 600 /mnt/gentoo/usr/src/initramfs/dev/console c 5 1

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

root #mknod -m 660 /mnt/gentoo/usr/src/initramfs/dev/mmcblk0p4 b 179 4

root #chgrp disk /mnt/gentoo/usr/src/initramfs/dev/mmcblk0p4

Important
If a block device other than that used in the example has been encrypted, the name of the device node and the major and minor numbers corresponding to the main partition must be used instead.

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 /boot/. The resulting file can be found by simply listing the files starting with initramfs:

root #ls /boot/initramfs*

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