Gentoo Linux Genkernel Guide

1.  Introduction

Rationale

For users who are not privy to kernel compilation, genkernel is a tool to automate this process. It can help you create a kernel image akin to those available on Gentoo Installation CDs, which are designed to auto-detect the hardware configuration of your system. Some users may also be interested in using genkernel for hardware requiring initialization and a working kernel before the system starts up. Since genkernel automatically compiles your kernel modules, you can use hardware that may require certain module parameters to be loaded for proper operation.

Target Audience

If you are either uncertain about how to compile a kernel, or are just unfamiliar with your hardware configuration, genkernel is a very handy tool. It is designed to take the pain out of the kernel compiling process, and supports most hardware by default.

However, if you know what drivers are required by your system, you may be able to further reduce the time taken to compile the kernel. This is possible since you can direct genkernel to only build drivers relevant to your hardware. Oftentimes, the number of drivers required by your system will be fewer (implying a shorter kernel compilation time) than the default configuration provides.

Installing genkernel

To obtain genkernel, run emerge genkernel from the command line. If you are using the Gentoo Reference Platform (GRP), remember to install binary packages by passing the -k flag to emerge. Since the GRP is bundled with an older version of genkernel, the flags may be different. In any case, consult genkernel --help for help on how to use the version of genkernel installed on your system.

2.  Working with genkernel

How to use genkernel

Although there are several ways to run genkernel, the least-intrusive approach is provided by genkernel all. Here, a generic configuration which works well for most systems is used. As was mentioned earlier, this approach is not without drawbacks; most of the modules created are useless to the average user and may increase compile time. Below is an illustration of a more efficient approach, achieved by passing certain flags to genkernel as root:

# genkernel --splash --no-install --no-clean --menuconfig all

The above operation causes genkernel to create a framebuffer splash-enabled kernel (--splash) that will have to be manually installed (--no-install). While preparing the kernel source tree, genkernel will refrain from cleaning out any preexisting object files present in the source tree (--no-clean). A menu-driven kernel configuration utility will be displayed that allows the user to select which modules will be built for the system (--menuconfig).

There are other flags which alter the result provided by genkernel. For instance, replacing --no install with the --install flag allows genkernel to automatically install the new kernel in the /boot directory. Using the --mountboot flag allows genkernel to mount your /boot partition automatically, if necessary.

Remember, genkernel is designed to make kernel compilation easy and stress-free. For this reason, genkernel features several flags to ease the kernel compilation effort. For example, there are flags to help with kernel configuration, while others affect the actual compilation. Some flags even help debug the compilation process. For those interested in further optimization, there are flags that affect kernel assembling, packaging and even kernel initialization.

The rest of this chapter examines the functionality of various flags and actions available for genkernel. Some of the flags have variants which perform a converse operation. The converse variants carry the no- prefix, and their effects are enclosed within the square brackets, [].

Configuration Flags

The configuration flags listed below exist to help you decide what features should be enabled or disabled in the kernel prior to compilation. You can even choose whether or not the configuration file created in the process should be saved. The following are the primary configuration flags:

• --no-menuconfig: Activates [or deactivates] the make menuconfig command (which invokes an interactive, menu-based kernel configuration utility), before building the kernel.
• --gconfig: Provides a kernel configuration utility which depends on the GTK+ libraries. The advantage of this option is that most users find it easier and clearer to configure the kernel using this tool, since it relies on the X-windowing system. The disadvantage of this option is that you need the X-windowing system to use it, so it will not work on the command line.
• --xconfig: Provides a kernel configuration utility which depends on the QT libraries. The advantage of this option is that most users find it easier and clearer to configure the kernel using this tool, since it relies on the X-windowing system. The disadvantage of this option is that you need the X-windowing system to use it, so it will not work on the command line.
• --no-save-config: Saves [or does not save] the kernel configuration to a file in the /etc/kernels/ directory for later use.

Compilation Flags

The following flags usually take effect during the actual compilation:

• --kerneldir=/path/to/sources/: Specifies an alternative kernel source location, rather than the default /usr/src/linux/ location.
• --kernel-config=/path/to/config-file: Specifies what alternative kernel configuration will be used, rather than the default /path/to/sources/.config file.
• --module-prefix=/path/to/prefix-directory/: Specifies a prefix to the directory where kernel modules will be installed (default path is the /lib/modules/ directory.)

• --no-clean: Activates [or deactivates] the make clean command before compiling your kernel. The make clean command removes all object files and dependencies from the kernel's source tree.
• --no-mrproper: Activates [or deactivates] the make mrproper command before kernel compilation. Like the make clean command, make mrproper removes all object files and dependencies from the kernel's source tree. However, any previous configuration files (in /path/to/sources/.config or /path/to/sources/.config.old) will also be purged from the kernel's source tree.
• --oldconfig: Issues the make oldconfig command, which attempts to collect configuration information for the system's architecture from a generic script in /usr/share/genkernel/. This is a non-interactive process; no user input is entertained. Also, if --oldconfig is used in conjunction with --clean, the latter flag is negated, resulting in the activation of the --no-clean flag.

• --callback="echo hello": Calls the specified arguments (echo hello, in this case) after the kernel and the relevant modules have been built, but before building the initrd image. This may be useful if you want to install external modules in the initrd image by emerging the relevant item(s) with the callback feature, and then redefining a genkernel module group.

• --no-install: Activates [or deactivates] the make install command, which installs your new kernel image, configuration file, initrd image and system map onto your mounted boot partition. Any compiled modules will be installed as well.
• --no-initrdmodules: Refrains from copying any modules to the genkernel-created initrd image. This flag is an exception to the rule about the no- prefix; omission of this prefix creates an invalid genkernel flag.
• --genzimage: Creates the initrd image, prior to the kernel image. (This hack currently applies only to PPC Pegasos systems.)

Compiler Flags

The following flags are supported by genkernel, and are passed to the relevant applications while the kernel is being assembled. These flags affect the compiler used for the kernel compilation process, albeit at a much lower level.

• --kernel-cc=someCompiler: Specifies the compiler employed during the kernel compilation process.
• --kernel-ld=someLinker: Specifies the linker employed during the kernel compilation process.
• --kernel-as=someAssembler: Specifies the assembler employed during the kernel compilation process.
• --kernel-make=someMake: Specifies an alternative to the GNU make utility employed during the kernel compilation process.

• --utils-cc=someCompiler: Specifies the compiler employed during the compilation of support utilities.
• --utils-ld=someLinker: Specifies the linker employed during the compilation of support utilities.
• --utils-as=someAssembler: Specifies the assembler employed during the compilation of support utilities.
• --utils-make=someMake: Specifies an alternative to the GNU make utility employed during the compilation of support utilities.

• --makeopts=-jX: Specifies the number of concurrent threads that the make utility can implement while the kernel (and utilities) are being compiled. The variable 'X' is a number obtained by adding one (1) to the number of CPUs used by the system. So, for a system with one CPU, the appropriate flag is -j2; a system with two CPUs will use the -j3 flag, and so on. (A system with one processor that supports Hyper-Threading™ (HT) Technology can use the -j3 flag, provided Symmetric Multi-Processing (SMP) support is enabled in the kernel.)

Debugging Flags

The use of debugging flags during the kernel compilation process controls the amount of information reported, as well as the presentation of said data.

• --debuglevel=verblevel: Controls the level of verbosity for information provided by genkernel. The variable verblevel is an integer between 0 and 5. The level '0' represents minimal output, while '5' provides as much information as possible about genkernel's activities during the kernel compilation process.
• --debugfile=/path/to/outputfile: Ignores the value set by the --debuglevel argument, and sends all debugging data produced by genkernel to the specified output file, which is located at /var/log/genkernel.log by default.
• --no-color: Activates [or deactivates] colored output of debugging information (reported by genkernel) using escape sequences.

Initialization Flags

The flags here are used to create certain effects during system startup. Some of these flags are primarily for aesthetics, while others may be essential for enabling certain features on the system.

• --no-splash: Activates [or deactivates] support for framebuffer splash support in the genkernel-built initrd image. To override the default theme used by fbsplash, use --splash=PreferredTheme (where PreferredTheme is the title of one of the directories inside the /etc/splash/ directory.
• --splash-res=PreferredResolution: This flag allows you to select which splash screen resolutions will be supported in the initrd during the start-up of the system. This is useful for two reasons: First, you are able to select only the splash screen resolution(s) relevant to your system. Second, you avoid the unnecessary increase in the disk space required by initrd (since the initrd does not have to support resolutions that are irrelevant for your system configuration.) However, you may want to omit this flag if the kernel is being compiled for an Installation CD; this allows splash support for all possible resolutions.
• --do-keymap-auto: Force keymap selection during the boot sequence.
• --lvm2: Includes support for storage using via Logical Volume Management (LVM2) from static binaries, if available to the system. Relevant (static) LVM2 binaries are compiled if they are unavailable. Be sure to install the lvm2 package on your system with emerge lvm2 before enabling this flag, and review the Gentoo LVM2 Installation guide.
• --evms2: Includes support for storage using the Enterprise Volume Management System (EVMS2), if available. Be sure to install the evms package on your system with USE=static emerge evms2 before using this (genkernel) flag. (Omitting the USE=static flag during package installation will fail to include the necessary static binaries.)
• --dmraid: Includes support for DMRAID; the utility which creates RAID mappings using the kernel device-mapper subsystem. DMRAID discovers, activates, deactivates and displays properties of software RAID sets (ATARAID, for example) and contained DOS partitions.
• --luks: Includes support for Linux Unified Key Setup or LUKS. This will allow you to use a device encrypted by LUKS which contains the root filesystem. On the bootloader, you then set that encrypted device as the value of crypt_root (and real_root shall be the unencrypted device LUKS creates).
• --linuxrc=/path/to/your/linuxrc: Specifies a user-created linuxrc — a script that is initialized during the start-up stage of the kernel, prior to the actual boot process. (A default linuxrc script should be in the /usr/share/genkernel/ directory.) This script allows you to boot into a small, modularized kernel and load the drivers that are needed (as modules) by the system.
• --cachedir=/path/to/alt/dir/: Overrides the default cache location used while compiling the kernel.
• --tempdir=/path/to/new/tempdir/: Specifies the location of the temporary directory used by genkernel while compiling the kernel.
• --unionfs: Includes support for the Unification File System in the initrd image.

Miscellaneous Flags

The assortment of flags listed below are supported by genkernel, but do not fit neatly into any of the other categories:

• --mountboot: Detects whether or not the /boot/ directory needs to be mounted on a separate partition. It will check /etc/fstab script for instructions on how to mount the boot partition on a file system (if needed).
• --kernname=NickName: Allows you to modify the name of the kernel and initrd images in the /boot/ directory, so that the images produced are kernel-NickName-version and initramfs-NickName-version.

Possible Actions

An action tells genkernel what to build. Currently, the following actions are supported:

• initrd: Only builds the initrd image
• bzImage: Only builds the kernel image
• kernel: Only builds the kernel image and modules
• all: Builds all stages — the initrd, kernel image and modules.

The last action, all, is recommended for most users since it builds the stages required for a functional kernel. Remember, an action simply tells genkernel what to build, not install.

Bootloader Configuration

To set up genkernel to work with your bootloader, three or four changes should be applied to the bootloader's configuration file:

1. Add root=/dev/ram0 and init=/linuxrc to the kernel parameters passed to the kernel image.
2. Add real_root=/dev/hda3, for example, to the kernel parameters passed to the kernel image, if /dev/hda3 contains your root partition.
3. If you are using splash, add a suitable mode line such as vga=0x317 to the parameters passed to the kernel and also add splash=verbose or splash=silent depending on the verboseness you require from your bootloader.
4. Add the initrd information as required by the bootloader. Consult the Bootloader Configuration Chapter of the Gentoo Handbook for details on how to make your bootloader initrd-aware.

3.  Configuration Options

Editing /etc/genkernel.conf

Passing flags to genkernel from the command line can be cumbersome, especially if you have about a dozen flags:

# genkernel --debuglevel=5 --no-color --no-mrproper --clean --splash \
--kerneldir=/path/to/alternate/kernel/sources --install --menuconfig \
--kernel-config=/path/to/preferred/configfile --save-config --mountboot all

Fortunately, there is a configuration file where most of the basic options can be set (or changed) as necessary. What follows is a rundown of the more relevant options:

• MENUCONFIG=[yes|no]: This option is equivalent to the --menuconfig flag used by genkernel, which in turn uses the make menuconfig command to invoke a command-line based kernel configuration utility. To invoke the utility automatically during kernel configuration via this script, set this option to 'yes' here; otherwise, choose 'no'.
• CLEAN=[yes|no]: Setting this option to 'yes' is equivalent to the --clean flag used by genkernel, and invokes the make clean command to remove all object files and dependencies from the kernel's source tree. Setting this option to 'no' creates a cascade effect — it is equivalent to genkernel's --no-clean flag, which disables the make clean command and implies genkernel's --no-mrproper flag — essentially nullifying the make mrproper command.
• MRPROPER=[yes|no]: Setting this option to 'yes' is equivalent to --mrproper flag used by genkernel, and invokes the make mrproper command, which purges the kernel source tree of any configuration files. Selecting 'no' here is equivalent to genkernel's --no-mrproper flag, which disables the make mrproper command.
• MOUNTBOOT=[yes|no]: Setting this option to 'yes' is equivalent to the --mountboot flag, and automatically mounts the /boot/ directory (if needed) at compile time. If the /boot/ directory is on a separate partition, consider enabling this option; it will make for one less (essential) step to remember later.
• SAVE_CONFIG=[yes|no]: After configuring the kernel, the selected options are stored as .config in the kernel source tree. This script may be overwritten during the next kernel compilation, or even purged from the kernel source tree. Choosing 'yes' here is equivalent to the --save-config flag, and stores all options selected during kernel configuration as a script in the /etc/kernels/ directory. Choosing 'no' preserves the status quo.
• USECOLOR=[yes|no]: Setting this option to 'yes' is equivalent to the --color flag, which colors genkernel's output to ease debugging (when needed.)
• DEBUGLEVEL=[0|1|2|3|4|5]: This option is for adjusting the verbosity of the output produced by genkernel — setting this option to '0' with --debuglevel=0 will suppress all output produced by genkernel; setting this option to '5' with --debuglevel=5 provides the user with all output produced by genkernel.

By choosing the appropriate options in /etc/genkernel.conf, you can halve the number of flags passed to genkernel from the command line:

# genkernel --splash --kerneldir=/path/to/alternate/kernel/sources \
--kernel-config=/path/to/preferred/configfile --install all

Identical results are obtained from both approaches, but the latter has most of the options stored in a script that can be modified at a later date.

4.  Network-Booting with genkernel

Network Booting from an Installation CD

The genkernel utility can build kernel and initrd images that provide support for network booting, or netbooting. With any luck, you should be able to netboot any recent computer into the environment provided by the Installation CD.

The magic lies in genkernel's linuxrc script: it will try to netmount the Installation CD using NFS. From there, the init scripts of the Installation CD can take over, as if the CD was present locally.

Building Kernel and Initrd Images with Support for Netbooting

To enable support for netbooting, include the following options while configuring the kernel:

First, the kernel image must include the drivers for your Network Interface Cards (NIC). Normally, drivers for such devices will be compiled as modules. However, it is essential (for netbooting) that you have such drivers compiled directly into the kernel image and not as modules.

Device Drivers --->
   Networking Support --->
      Ethernet (10 or 100Mbit)  --->
         [*] Ethernet (10 or 100Mbit)
         <*>   the driver for your network card
(Be sure to select <*> and not <M>)

Secondly, we suggest that you enable IP: kernel level autoconfiguration and the IP: DHCP support options. This avoids an unnecessary layer of complexity since the IP address and the NFS path to the Installation CD can be configured on a DHCP server. Of course, this means the kernel command line will remain constant for any machine — which is very important for etherbooting.

Device Drivers --->
   Networking Support --->
      Networking options
         [*] TCP/IP networking--->
         [*]   IP: kernel level autoconfiguration
         [*]     IP: DHCP support
(These options tell the kernel to send a DHCP request at bootup.)

Additionally, you should enable SquashFS because most modern Gentoo Installation CDs require it. Support for SquashFS is not included with the generic kernel source tree. To enable SquashFS, apply the necessary patches to the generic kernel source or install gentoo-sources.

File systems--->
   Miscellaneous filesystems --->
      [*] SquashFS 2.X - Squashed file system support

Once the compilation process is completed, create a compressed tarball (tar.gz) that contains the kernel's modules. This step is only necessary if your kernel version does not match the kernel image version on the Installation CD.

(Create a tar.gz containing all the modules)
# cd /
# tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/

Depending on your network boot mechanism, you will need to do some of the following steps:

(Create an etherboot image)
# emerge mknbi
# cd /boot
# mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img

(Create a OpenBoot / SPARC64 TFTP image)
# emerge sparc-utils
# cd /boot
# elftoaout kernel... -o kernel.aout
# piggyback64 kernel.aout System.map-... initrd-...
# mv kernel.aout openboot.img (This is the boot image)

(PXE does not need any more steps, the kernel and initrd can be used as is)

Finally, copy this kernel to your TFTP server. The details are architecture-dependent and are beyond the scope of this guide. Please refer to the documentation for your platform.

NFS Setup

To setup a NFS share that contains the Installation CD, use the loop device to mount the ISO image and then copy the contents of the CD into the NFS share. As a nice extra, genkernel's initrd scripts will extract all tar.gz files located in the /nfs/livecd/add/ directory. All you have to do here is copy the modules-X.Y.Z.tar.gz archive to the /nfs/livecd/add/ directory.

(This assumes that /nfs/livecd is an exported NFS share)
# mount /tmp/gentoo-livecd.iso /mnt/cdrom -o loop
# cp -p /mnt/cdrom /nfs/livecd
# umount /mnt/cdrom

(Copy the modules.tar.gz into /add)
# mkdir /nfs/livecd/add
# cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add

DHCP Setup

The netboot images will ask your DHCP server for an IP as well as a root-path parameter. Both can be specified per host using a MAC address to identify machines:

...

host netbootableMachine {
         hardware ethernet 11:22:33:44:55:66;
         fixed-address 192.168.1.10;
         option root-path "192.168.1.2:/nfs/livecd";
}
# Here, 192.168.1.2 is the NFS server
# While 192.168.1.10 will be the IP address of the netbooted machine
...

Netbooting Instructions

Netbooting itself is again very platform-specific. The important part is to specify the ip=dhcp and init=/linuxrc parameters on the kernel command line, as this will bring up the network interface and tell the initrd scripts to mount the Installation CD via NFS. Here are some platform-specific tips:

# Etherboot - insert the etherboot disk into the drive and reboot
# The kernel command line was specified when the image was constructed

# Sparc64 - Hit Stop-A at the boot prompt
ok boot net ip=dhcp init=/linuxrc

# PXE - Setup pxelinux (part of syslinux),
then create a pxelinux.cfg/default along the lines of:

DEFAULT gentoo
TIMEOUT 40
PROMPT 1

LABEL gentoo
    KERNEL kernel-X.Y.Z
    APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp

5.  Conclusion

To Automate or not to Automate?

The purpose of genkernel is to provide an (easier) alternative to the time-tested approach to kernel compilation. As always, you are free to decide on whether or not you want to automate the kernel compilation process.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.