kexec-loader manual

Version: 2.0

1. Introduction
2. Usage
3. Building kexec-loader
4. Support
- 4.1. Website
- 4.2. Developer

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:

timeout <integer>
Number of seconds to wait before booting the default target, the first target will be booted if none are marked as default.
grub-path <path>
Load device.map and menu.lst from a GRUB installation at this directory. You must specify a device.
grub-map <GRUB device> <device>
Map a GRUB device, hd0 => sda will map the disk hd0 to sda whereas hd0,a => sda5 will map BSD partition a on hd0 to sda5, kexec-loader does not support BSD disklabels so you will need to map any BSD partitions you intend to boot. Mappings in kexec-loader.conf will overrule those in device.map.
kmod <module> <args>
Set options to be passed to a kernel module if it is loaded.

The following directives are per-target:

title <text>
Set the target title, all targets must begin with a title directive.
root <device>
Set the root device, you must specify a root device, even if all paths specify their own device.
kernel <path>
Path to the kernel, all targets must specify a kernel.
initrd <path>
Path to an initrd/initramfs.
cmdline <text>
Set the command line which will be passed to the target kernel.
append <text>
Set the kernel command line using --append, this appears to do exactly the same thing as cmdline, but is implemented for completeness.
module <path> [args]
Load and pass a multiboot module to the target kernel.
default
Mark this target as the default.
reset-vga
Reset the VGA adaptor before starting the kernel, may be useful if you get garbled or no output on bootup.

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.

root <device>
Set the root device, you must specify a root device to boot.
kernel <path>
Path to the kernel, you must specify a kernel.
initrd <path>
Path to an initrd/initramfs.
cmdline <text>
Set the command line which will be passed to the target kernel.
append <text>
Set the kernel command line using --append, this appears to do exactly the same thing as cmdline, but is implemented for completeness.
module <path> [args]
Load and pass a multiboot module to the target kernel.
reset-vga
Reset the VGA adaptor before starting the kernel, may be useful if you get garbled or no output on bootup.
boot
Boot the system using settings entered in the shell.
disks
Display a list of disks and partitions which have been detected by Linux.
ls <directory>
List the contents of a directory.
find <filename> <directory>
Search a directory for files matching the pattern 'filename', filename may include the wildcard characters * or ?.
cat <filename>
Print the contents of a file to the console.
exit
Leave the shell and go back to the menu.

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:

GNU C compiler
Linux kernel headers
GNU Make
cpio archiver
Toolchain
zlib with headers

3.2. Compiling

To compile kexec-loader, use the following commands:

HOST=i386-linux-uclibc make
./mkinitramfs.sh 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:

Create a 1.44MB file and format using mkfs.vfat
Install and configure SYSLINUX on the floppy image
Copy a UPX compressed kernel image to the floppy image
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.