Genkernel

genkernel is used to automate the build process of the kernel and initramfs. Some of the general features:
 * configure the kernel sources
 * build bzImage and copy to
 * create initramfs and copy to
 * create symlinks in
 * add custom content to initramfs for encryption, splash images, extra modules etc.
 * compress initramfs
 * configure the bootloader

Installation
Install :

Genkernel Invocation
The general form of genkernel invocation is as follows:

Options
The actual behavior of genkernel depends on a large variety of options, the majority of which,  can be set/unset in the    file or passed via  the genkernel command. Options passed over the command line take precedence over options defined into. This file is very well documented but let's examine some of the most commonly used ones here. For a more complete explanation, please refer to the comments in itself or to the output of the   command.

Options acting on user interactivity
The configuration options listed below help you decide how you will interact with the configuration process. You can even choose whether or not the configuration file created in the process should be saved. The following are the primary configuration options:


 * --[no-]menuconfig: Activates [ or deactivates] the  command (which invokes un interactive configuration menu) 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.


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

Options acting on the resulting system
The configuration options listed here defines which features will, or won't be enabled in the resulting kernel and initrd.


 * --[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 option 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 option 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.


 * --lvm: 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 option, and review the LVM article on the Gentoo wiki.


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


 * --disklabel: Adds support for disk label and UUID support to your initrd.


 * --iscsi: Adds support for iSCSI to your initrd.


 * --multipath: Adds support for Multipath to your initrd.


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


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

Options acting on the tools used for building
The following options are supported by genkernel, and are passed to the relevant applications while the kernel is being assembled. These options affect the compiling tools 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 option is -j2; a system with two CPUs will use the -j3 option, and so on. (A system with one processor that supports Hyper-Threading™ (HT) Technology can use the -j3 option, provided Symmetric Multi-Processing (SMP) support is enabled in the kernel.)

Options acting on the compilation process
The following options 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 option is negated, resulting in the activation of the --no-clean option.


 * --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-ramdisk-modules: Refrains from copying any modules to the genkernel-created initrd image. This option is an exception to the rule about the no- prefix; omission of this prefix creates an invalid genkernel option.


 * --all-ramdisk-modules: Copies all available modules to the genkernel-created initrd image.


 * --genzimage: Creates the initrd image, prior to the kernel image. (This hack currently applies only to PPC Pegasos systems.)

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


 * --loglevel=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.


 * --logfile=/path/to/outputfile: Ignores the value set by the --loglevel argument, and sends all debugging data produced by genkernel to the specified output file, which is located at by default.


 * --no-color: Activates [or deactivates] colored output of debugging information (reported by genkernel) using escape sequences.

Action
The action passed on the command line with the  command, tells genkernel  what you want it to do - the following actions are supported:


 * all: Builds all stages — the initrd, kernel image and modules.


 * bzImage: Only builds the kernel image


 * kernel: Only builds the kernel image and modules


 * initramfs: Only builds the initramfs/ramdisk image


 * ramdisk: Only builds the initramfs/ramdisk image

Genkernel First Invocation
Although there are several ways to run genkernel, the least-intrusive approach recommended for most users is provided by. 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 options to genkernel as root:

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

Replacing --no-install with the --install option allows genkernel to automatically install the new kernel in the /boot directory, and will create symlinks for you if --symlink is specified. Using the --mountboot option allows genkernel to mount your /boot partition automatically, if necessary.

Using Genkernel to change your kernel
The first thing you should do is to allow the triggering of make menuconfig in the file:

Forcing the use of the configuration menu in /etc/genkernel.conf

File Management by genkernel
While using genkernel, the user has to be aware of some aspects relating to kernel configuration and kernel image files management and the way the kernel sources are handled by the system.

Source Files used by genkernel
After an, whenever new sources are available, a new kernel source directory is created under  to host them. Normally, the active kernel sources directory is pointed by the   symlink.

The directory might look like this:

ls -l /usr/src

The  symlink can be changed in different ways.


 * If the  USE flag is set in, the   symlink is automatically updated to point to the newly emerged sources.


 * If the previous USE flag is not set, the user can change the destination of the symlink using the   command.

Whatever it is, genkernel always uses the sources pointed by this symlink.

Kernel Configuration file used by genkernel
If a kernel compilation has already been run with the active kernel sources, there might be a file inside the directory that contains the kernel configuration that has been applied while creating the last bzimage of the kernel. This file is named, for example where x86_64 might be substituted with your architecture,  3.7.9 might be substituted with the version of the sources you are using and r1 with the release of the sources..

It is this file that is used as a starting configuration when running   }}.

If it is the first time you run, or if the previous has not been saved, this file is substituted with a default configuration file that resides into  where x86_64 might be substituted with you actual architecture.

Saving the compiled configuration
If the  genkernel option  is activated, either from the command line or inside, the compiled kernel configuration is saved (with the name given above) into the  directory. At the same time, the configuration is saved in the .config file in directory but this file is not reused on the next   run.

Installing the kernel and initramfs into the /boot directory
The all action specified when invoking genkernel, ask  to install the kernel image and the initramfs into the  directory. In order to do it in a convenient manner, set the following in your :

Setting up kernel and initramfs auto-saving in /etc/genkernel.conf


 * The first parameter speaks by itself.


 * The second parameter tells genkernel to save the compiled kernel configuration into


 * The last two options tell genkernel to automatically update the grub configuration. In practice, the following happens:


 * if a previous kernel image with the same name already exist, it is renamed by appending .old to its name. A symlink kernel.old is automatically created that points to it.


 * the new kernel takes the place of any kernel with the same name into . If it is the first time a kernel is compiled, a symlink kernel is automatically created that points to the new kernel.

After running, the  directory might look like this:

jaaf@localhost ~ $ ls -al /boot total 41336 drwxr-xr-x 3 root root   4096 20 avril 17:23. drwxr-xr-x 24 root root   4096 15 sept. 12:31 .. lrwxrwxrwx 1 root root       1 24 févr. 2013 boot ->. drwxr-xr-x 2 root root    4096 24 févr. 2013 grub lrwxrwxrwx 1 root root      40 20 avril 17:23 initramfs -> initramfs-genkernel-x86_64-3.7.10-gentoo -rw-r--r-- 1 root root 1314412 20 avril 17:23 initramfs-genkernel-x86_64-3.7.10-gentoo -rw-r--r-- 1 root root 1313548 21 mars   2013 initramfs-genkernel-x86_64-3.7.10-gentoo.old -rw-r--r-- 1 root root 1295344 25 févr. 2013 initramfs-genkernel-x86_64-3.7.9-gentoo -rw-r--r-- 1 root root 3310324 25 févr. 2013 initramfs-genkernel-x86_64-3.7.9-gentoo.old lrwxrwxrwx 1 root root      44 20 avril 17:23 initramfs.old -> initramfs-genkernel-x86_64-3.7.10-gentoo.old lrwxrwxrwx 1 root root      37 20 avril 17:23 kernel -> kernel-genkernel-x86_64-3.7.10-gentoo -rw-r--r-- 1 root root 4866656 20 avril 17:23 kernel-genkernel-x86_64-3.7.10-gentoo -rw-r--r-- 1 root root 4866560 21 mars   2013 kernel-genkernel-x86_64-3.7.10-gentoo.old -rw-r--r-- 1 root root 4552288 25 févr. 2013 kernel-genkernel-x86_64-3.7.9-gentoo -rw-r--r-- 1 root root 3400736 25 févr. 2013 kernel-genkernel-x86_64-3.7.9-gentoo.old lrwxrwxrwx 1 root root      41 20 avril 17:23 kernel.old -> kernel-genkernel-x86_64-3.7.10-gentoo.old jaaf@localhost ~ $

Configuring the bootloader
You can use the symlinks presented above in your bootloader's configuration, so that, even if your new kernel is not bootable, you can always boot on the old one.

To allow the kernel and intird provided by genkernel to run correctly, you should provide a minimum information in your bootloader s' configuration file :


 * Add real_root=/dev/sdax, to the kernel parameters passed to the kernel image, where /dev/sdax contains your root partition.


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


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

Here is how the file might look.

An example of grub.conf file

Preserving your working files

 * The first file to preserve is the kernel configuration file in . If you didn't change the source prior to the recompilation of your kernel, the previously used name for this file will be used anew. It is the reason why you should ever rename the previous configuration file with a name of your own.


 * The second important thing is to preserve your already bootable kernel and initramfs images. The way to accomplish this depends on the context:


 * 1) If the last kernel you compiled, is bootable, running   anew will rename this kernel (and similarly initramfs) image to  and create a new . This mean that even if your new kernel is not bootable, you will always be able to boot the old one.


 * 1) If the last kernel you compiled is not bootable and sources haven't changed since you compiled a bootable one, prior to run   anew, first delete the new kernel image, remove the .old suffix from the last bootable one. If you don't do so and the kernel you compile is not bootable for the second time, your bootable  will be kicked out by the renaming of the non bootable, letting you with an unbootable system. Please have the same reasoning for initramfs.

Using previous kernel configuration while changing the sources
You can use your previous configuration using the make menuconfig option in your as follows:

Setting up make menuconfig into /etc/genkernel.conf

Network Booting with Genkernel 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.

Be sure to select <*> and not .

Secondly, we suggest that you enable  and the. 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.

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.

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.

To create a  containing all the modules:

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

To create an etherboot image:

To create a OpenBoot / SPARC64 TFTP image:

The file is the boot image.

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 directory. All you have to do here is copy the modules-X.Y.Z.tar.gz archive to the directory.

The following assumes that is an exported NFS share:

Now copy the file into :

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:

Sample client dhcpd.conf setup

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.

For etherboot, insert the etherboot disk into the drive and reboot. The kernel command line was specified when the image was constructed. With Sparc64, hit - at the boot prompt and enter:

For PXE, setup pxelinux (part of syslinux), then create a pxelinux.cfg/default along the lines of:

Default pxelinux.cfg file

Introduction
If you installed an initramfs with genkernel, you should definitely take a look at the various boot options that you can (or need to) define in your bootloader configuration. The most common ones are added to this guide for your reference.

Loading LVM or software-RAID
If your system uses LVM or software-RAID, you undoubtedly have built the initramfs using the --lvm and --mdadm options (didn't you). However, you should not forget to enable support during boot as well. This can be done using the dolvm and domdadm options.

Enabling LVM and/or MDADM support

Booting in single-user mode
If for some reason boot-up fails, you might be able to rescue your system by booting in the single-user mode. This will only load the really necessary services and then drop you to a rescue (root) shell.

Booting in single-user mode

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Tim Yamin
 * Jimi Ayodele
 * Thomas Seiler
 * Joshua Saddler
 * Sebastian Pipping
 * José Fournier