kexec-loader manual

Version: 2.0

Copyright © 2007-2009 Daniel Collins
Copyright © 2008-2009 Philip Kent

1. Introduction

kexec-loader is a Linux based bootloader that allows you to boot Linux and multiboot systems from storage devices your BIOS does not support, such as USB drives and PCI expansion cards. It fits on a 1.44MB floppy, supports most block devices supported by Linux and is easy to use. kexec-loader supports reading GRUB configuration files, this allows kexec-loader to be used as a drop-in replacement for GRUB by merely setting the GRUB installation path.

The kexec-loader project site has prebuilt disk images available for download, unless you have a very good reason for compiling from source, this is the best option, as the process for building disk images is complicated and requires a good understanding of Linux. The prebuilt images have support for PC floppy drives, USB mass storage devices and the FAT filesystem, other devices and filesystems may be used if the appropriate modules are loaded.

2. Usage

2.1. Device/Path syntax

There are three ways of specifying devices, you can specify the device name which may change without warning, this is only recommended on systems that have a single drive, for example a single USB drive being booted by kexec-loader on an internal floppy drive. You may also use 'LABEL=foobar' and 'UUID=xxxx' to specify the volume label and UUID, respectively.

If a device name contains a colon it is assumed you are manually specifying the filesystem type, for example 'ext3:hda1' will overrule filesystem detection and attempt to mount the filesystem as ext3, this may be used if the detection is not working correctly.

You may specify a device in a path as well as a file, for example '(hda1)/boot/vmlinuz' will point to the /boot/vmlinuz file on hda1, instead of /boot/vmlinuz on the root device.

2.2. Kernel modules

You can load kernel modules which allow kexec-loader to support more devices/filesystems/etc, to load a kernel module simply copy it to the 'modules' directory on the boot floppy. If you are using an official disk image you can download the modules package appropriate for your kernel from the project site. Your kernel version is displayed at the top of the menu and when you start the shell.

These are not to be confused with multiboot modules, which are modules loaded by the bootloader and passed to a multiboot kernel, they are commonly used for the same purpose as Linux kernel modules, read your OS documentation for more information.

2.3. Configuration File

The kexec-loader configuration is stored in a text file named kexec-loader.conf on the boot floppy, it may be in UNIX or DOS format. There must be one directive per line with arguments seperated by spaces or tabs, lines beginning with a hash (#) are ignored. You may additionally load the configuration from a GRUB install, which allows kexec-loader to be a drop-in GRUB replacement.

The following directives are supported:

The following directives are per-target:

Where parameters are shown in <angled brackets>, they are required for that directive. Ones in [square brackets] are optional.

2.4. Shell

kexec-loader has a shell which can be used for configuring a target at boot time and performing some other actions. To access it press C on the menu screen, it is also displayed if there are no pre-configured targets available. You can scroll through the command history using the up/down arrow keys.

2.5. Debug Console

Once kexec-loader has started, debugging messages are sent to a separate console. By default the debug console is tty3, this can be changed by setting debug_tty on the kernel command line. Kernel messages are sent to tty2.

3. Building kexec-loader

3.1. Introduction

This section explains how to build a kexec-loader disk image, you must build a kernel and toolchain which is not explained in this document. I recommend using uClibc as a toolchain as glibc is too big to fit on a floppy, you must also use Linux 2.6.13 or above, as earlier versions did not have the kexec syscalls.

You will need the following to compile kexec-loader:

3.2. Compiling

To compile kexec-loader, use the following commands:

HOST=i386-linux-uclibc make
./ initramfs.cpio

The first command assumes your toolchain was built to target i386-linux-uclibc, in which case the various tools such as gcc can be invoked as i386-linux-uclibc-gcc, ensure you set this to the correct target, or the compile may fail, or end up being compiled with the wrong toolchain. You must also make sure that the toolchain bin directories are included in $PATH.

The first command compiles kexec-loader, downloads, patches and compiles kexec-tools, then links them as the binaries src/kexec-loader and src/kexec-loader.static, which are dynamically and statically linked respectively. The second command creates a Linux initramfs archive as initramfs.cpio, the initramfs contains kexec-loader.static as /init, some device nodes and empty directories.

3.3. Creating a Disk Image

This is a fairly generic floppy building method:

  1. Create a 1.44MB file and format using mkfs.vfat
  2. Install and configure SYSLINUX on the floppy image
  3. Copy a UPX compressed kernel image to the floppy image
  4. Copy misc. files (kexec-loader.conf, README, etc)

Please note that the kexec-loader initramfs is included in the kernel for space reasons, however, this is not required should your chosen bootloader (to load kexec-loader) can support loading it. In addition the UPX compression step is optional.

4. Support

4.1. Website

For information on kexec-loader, including current development and latest releases, please see the project website.

4.2. Developer

The developer of kexec-loader, Daniel Collins (aka solemnwarning), can often be found on the Freenode IRC network. To contact solemnwarning, you can use the following e-mail address: