kexec-loader manual

Version: 1.4.1.

© 2008 Daniel Collins
© 2008 Philip Kent

1. Compilation

1.1. Introduction

kexec-loader is a boot loader which loads a Linux kernel, then displays a GRUB-like menu so you can select a kernel to boot using kexec. It is designed for systems where the BIOS does not support booting from some devices (e.g. your kernel is on a USB memory key which the BIOS does not support).

If you have downloaded one of the pre-built disk images, you do not need to read the rest of this section, and you can skip to Section 2. A pre-made disk image is probably more suitable to the end user in most cases, as the provided image supports IDE, SATA and USB and is pre-compiled. You can obtain it from the project's webpage.

1.2. New in kexec-loader 1.4.1

A summary of the new features in this release of kexec-loader is below. For a more detailed changelog, please see the ChangeLog file.

1.3. Requirements

To build kexec-loader, you require the following tools.

kexec-tools is included and built as part of the build process.

1.4. Build Instructions

In order to build kexec-loader, you first need a Linux kernel with support for the hardware you want to boot from. This kernel will need fit onto the device that will be used to boot, with sufficient space left for other files that will need to be on the device (such as kexec-loader itself and the boot loader).

Once you have your kernel, simply run "make" from the root of the kexec-loader source to build the kexec-loader binary. This will include downloading and building kexec-tools. It is recommended that you build a uclibc toolchain prior to this, then building kexec-loader using it, as this will make the resulting file smaller. To use a uclibc toolchain, do "HOST=i386-linux-uclibc make" instead of make.

Then run from the root directory of the distribution to build an initramfs containing kexec-loader.

1.5. Creating a Disk Image

Once you have a kernel and initramfs, you can then build a disk image. There are two ways to assemble the disk, which are below.

  1. Embed your initramfs inside your kernel (this is what is done by the prebuilt images) using menuconfig. You will have to rebuild your kernel.
  2. Just load it as an initramfs along with your kernel with a boot loader.

Regardless of the method you choose, you will need a bootloader such as syslinux. Build your image using your favourite method (such as using dd to produce an empty floppy image, formatting it then loop mounting it), put the kernel and initramfs (if any) on the disk, along with any boot loader configuration, install the boot loader and your disk is prepared.

2. Usage

2.1. Configuration File

kexec-loader uses a GRUB-like configuration file to find what menu options it needs to show. If you have downloaded one of the pre-made disk images, a sample configuration is stored on the disk that might be able to boot a Debian system.

kexec-loader will attempt to find a configuration in the following places in order, unless you choose to use grub (see below):

If you specify a device as a variable called kexec_config on the boot line (e.g. kexec_config=/dev/hda), then the named device will be put on the top of the list. Failing to load from that one, it will then go through the list.

The configuration must be called kexec-loader.conf and stored in the root of the filesystem and it must contain at least one section starting "title" OR have a grub_root to load a grub config file, or else it will have no kernels to load. You can put whitespace between the directives and their variables. Empty lines and lines beginning with a hash (#) are ignored.

As of kexec-loader 1.3, reading a grub configuration file is supported. The entries in the grub configuration file will be placed below all other entries). To use grub, use the relevant directives.

The directives are as follows.

Where parameters are shown in <angled brackets>, they are required for that directive. Ones in [square brackets] are optional. For mount and rootfs, if you do specify a fstype, it should be specified as ext2:/dev/hda1 for example.

Normally kexec-loader can detect the filesystem type, it supports autodetection for the following types.

Specifying no filesystem or "auto" will result in auto detection. For manual specification, enter the name of any filesystem that your kernel supports.

2.2. Using the Menu

To navigate the kexec-loader menu, use your arrow keys to select an item and press enter to boot it. A number of functions are available; press L to list the detected devices and their filesystems and R to re-read the configuration file. Press enter if you are on the device screen or an error and you want to escape.

Upon asking a kernel to boot, it may take a few seconds for it to load the kernel and switch to it. After switching, your new kernel will start and the boot process will happen as it would normally.

2.3. Built in shell

kexec-loader has a built in shell. To access it press "s" on the menu screen. This shell lets you set up a kernel to boot once kexec-loader has started. Therefore it has the same directives as mentioned above, except "default" and "title".

There are two further directives used to control kexec-loader, rather than set up a kernel to boot. They are:

To scroll through the command history, use the up and down keys. A maximum of 32 commands are remembered (upon exceeding this, the oldest command will be removed from the history to make space). Commands that are longer than the screen can hold will scroll, similar to the 'nano' text editor. Please note that this shell will be improved in subsequent releases.

2.4. Debug Console

Once kexec-loader has started all debugging messages, as well as Linux kernel messages are sent to a separate debug console. By default the debug console is /dev/tty2, this can be changed at boot by using the Linux cmdline, for example kexec_debug=/dev/ttyS0 writes all debug messages and kernel messages to the first serial port.

3. Support

3.1. Website

For information on kexec-loader, including current development and latest releases, please see its website at

3.2. Mailing List

A mailing is available for kexec-loader, subscription information and archives can be found at

3.3. Developer

The developer of kexec-loader, Daniel Collins (aka solemnwarning), can often be found on other discussion sites, such as the "Microsuck" forums and on freenode IRC. To contact solemnwarning, you can use the following e-mail address: