kexec-loader manual

Version: 2.3

Copyright © 2007-2011 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 it to be used as a drop-in replacement for GRUB.

If you need to build or modify kexec-loader for some reason please see the build.html file in the source archive, this details how to compile kexec-loader and build disk images.

2. Usage

2.1. Basic Configuration

By default, kexec-loader will attempt to find a GRUB installation and copy any compatible boot targets from it. This will work for most Linux systems, but you can manually specify boot targets in kexec-loader.conf instead if desired. Doing so will disable the GRUB autodetection unless grub-autodetect is explicitly set to 'on'.

timeout 10

title Generic Linux System (Kernel 2.6.20)
root hda1
kernel /boot/vmlinuz-2.6.20
cmdline root=/dev/hda1 ro
initrd /boot/initrd.img-2.6.20

title Generic Linux System (Kernel 2.6.21)
root hda1
kernel /boot/vmlinuz-2.6.21
cmdline root=/dev/hda1 ro
initrd /boot/initrd.img-2.6.21

It is also possible to reference files not on the root disk or filesystems by their volume label or UUID, as shown below.

root UUID=75ac0d6c-5dc0-402f-9f0f-9ab313816439
initrd (LABEL=otherdisk)/boot/initrd.img-2.6.21

2.2. Kernel Modules

If you are using an official kernel you will probably need to load additional modules for your system. The appropriate kernel modules can be downloaded from the same page the disk image came from. To install modules, simply copy them to the 'modules' directory on the kexec-loader boot disk, if the module is needed to access the boot disk use to insert it into the initramfs (initrd.img).

Some kernel modules (mainly for old, non-PnP hardware) may need to be passed additional arguments at load time, these can be specified in kexec-loader.conf like so:

kmod module-name arg1 arg2=value arg3 ...

If you are building your own modular kernel, multiple modules may be combined inside tar archives (optionally compressed with LZMA or gzip). This technique is used for the official modules to combine related/dependant modules and save space.

2.3. GRUB Configuration

In most cases, the system's GRUB configuration can be detected automatically, but if you want to manually specify the path of the GRUB folder (i.e where multiple GRUB installations may be found), you can use grub-path in kexec-loader.conf:

grub-path (hda1)/boot/grub

You may also need to manually map GRUB devices to filesystems, this is only required when the disk numbering is guessed wrong or BSD disklabels are in use. You can map entire disks or single filesystems using the grub-map directive:

grub-map hd0 sda
grub-map hd0,1 LABEL=root

# BSD disklabels are not currently detected automatically
grub-map hd0,a sda8

2.4. Changing the keymap

Linux's built-in US keymap will be used by default, which is also acceptable for some other keyboards since only the basic keys are used. If your keyboard needs a special keymap, download it from here and save it to the boot disk as keymap.txt.

2.5. Shell

There is a shell built into kexec-loader which can be used to configure and boot a target or list/find/read files to aid with configuring a boot target. To access the shell, press C at the menu screen, the shell will be displayed by default if there are no boot targets configured. The commands for configuring and booting a target are very similar to those in the configuration file, as shown below:

> root hda1
> kernel /boot/vmlinuz-2.6.20
> cmdline root=/dev/hda1 ro
> initrd /boot/initrd.img-2.6.20
> boot

This example will boot the first target example from the configuration file section, the syntax of the shell is exactly the same except you must type boot at the end to show you have finished configuring the boot target. Filenames may specify a disk at the beginning, just as in the configuration file.

The ls command lists the contents of a directory, directories have slashes appended to their names. The disk can be omitted from the path in the following example to use the root device.

> ls (fd0)/

The find command searches directories for files that match a pattern, the pattern may contain the * and ? wildcards which have the same meaning as in most shells. The following example searches the floppy disk for any files containing "linux" in their name. The path can be omitted to search the entire disk once a root device has been selected.

> find *linux* (fd0)/

3. Reference

3.1. Configuration Reference

The configuration file must be named kexec-loader.conf or kxloader.cfg, kexec-loader.conf will be checked for first. The file may be in UNIX or DOS format. Each line may contain a single directive, where the name and value(s) are seperated by spaces/tabs. Lines beginning with a hash (#) symbol are treated as comments.

All valid configuration directives are listed below. Parameters are shown in <angled brackets> are required for that directive, ones in [square brackets] are optional.

The following directives are global:

The following directives are per-target:

3.2. Shell Reference

The kexec-loader shell is designed to closely mimic a traditional UNIX shell, except the parsing is far simpler. Escaping or quoting spaces is unnecassary as the parser only breaks at spaces if the command is expecting multiple arguments, therefor if a command takes multiple arguments only the last one may contain spaces.

3.3. Kernel Command Line Options

The following options can be passed to kexec-loader via the kernel command line.

4. Support

4.1. Website

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