Version: 2.1.1
Copyright © 2007-2009 Daniel Collins
Copyright © 2008-2009 Philip Kent
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.
On startup kexec-loader looks for a configuration file named kexec-loader.conf in the root directory of the boot disk. If it does not exist it will attempt to load kxloader.cfg instead, this is to allow writing a configuration file on systems that only support 8.3 filenames such as DOS.
The configuration file below shows how to boot a simple Linux system with two kernel versions installed. Each target beginning with a title line will be displayed on the boot menu. If no key is pressed within 10 seconds the second entry will be booted automatically. If there are no targets with a default line the first one will be booted.
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
default
The next example does the same thing, but demonstrates how to specify a disk as part of the filename, this can be used to load files from disks other than the one specified on the root line. Directives that take a path and are not part of a target definition must specify the disk.
timeout 10
title Generic Linux System (Kernel 2.6.20)
root hda1
kernel /boot/vmlinuz-2.6.20
cmdline root=/dev/hda1 ro
initrd (hda1)/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 (hda1)/boot/initrd.img-2.6.21
default
It is also possible to reference a disk by its volume label or UUID, this may be useful in cases where the device name may change, for example a USB drive which is used on multiple machines. The following example shows how to use both, you can also use the LABEL/UUID syntax in filenames.
root LABEL=disklabel
root UUID=75ac0d6c-5dc0-402f-9f0f-9ab313816439
If you have a GRUB installation, kexec-loader can load its configuration. To use it you simply need to set the path of your GRUB install directory (containing menu.lst and device.map) in kexec-loader.conf:
grub-path (hda1)/boot/grub
On startup kexec-loader will read the list of GRUB devices from devices.map, it will use these to convert the BIOS disk numbers in menu.lst to Linux device names. All bootable entries in menu.lst will then be loaded and added to the boot menu. It will also load the default and timeout options from menu.lst if they are not specified in kexec-loader.conf.
If you want to override the device mappings in device.map, for example if GRUB is installed to a USB drive which is used on multiple machines, you can use the grub-map directive in kexec-loader.conf to specify new mappings. There are two types of device mappings possible, which are shown below.
grub-map hd0 sda
grub-map hd1,0 sda2
The first line maps the first BIOS disk (hd0) to Linux disk sda. The second line maps the first partition of the second BIOS disk (hd1,0) to the second partition on Linux disk sda. When mapping single partitions you can use the UUID/LABEL syntax as shown below.
grub-map hd0,0 LABEL=boot
grub-map hd0,2 LABEL=root
If you are running a modular kernel (All official builds use a modular kernel) you can load modules to support hardware, filesystems and encodings not supported by the base kernel. To install a module copy it to the modules directory on the boot disk, if the module is required to access the boot disk you can create a directory called modules in the initramfs and copy it there. One or more modules may be packaged in a tar file, or an LZMA compressed tar file with the .tlz extension.
Some modules or hardware combinations may require arguments to be passed to the module, this is usually for ISA and non-PnP hardware. If you have such hardware you can specify arguments to be passed in kexec-loader.conf, these will only be used for modules loaded after kexec-loader.conf.
kmod module-name arg1 arg2=value arg3 ...
If the file keymap.txt exists on the boot floppy, it will be loaded as the keymap. The official kexec-loader disks do not include a keymap.txt file, so the US kernel keymap will be used.
New keymap.txt files can be downloaded here, remember to rename them before use. If your keymap isn't available here, you can use the conv-keymap.pl script from the source download to generate one from a Linux console keymap. (normally found in /usr/share/keymaps)
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)/
ldlinux.sys
linux.cfg
kexec-loader.conf
syslinux.cfg
README.html
modules/
initrd.img
vmlinuz
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)/
(fd0)/ldlinux.sys
(fd0)/linux.cfg
(fd0)/syslinux.cfg
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 are seperated by spaces/tabs. Lines beginning with a hash (#) symbol are treated as comments.
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.
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.
Keymap files are loaded from the boot floppy, they must be stored in the root directory and named keymap.txt. The file format is a plain text file in UNIX or DOS format with one record per line. The record values are table, key index and action, seperated by tabs. For more information read the keymap.c file.
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:
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 and e2fsprogs, 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.
For information on kexec-loader, including current development and latest releases, please see the project website.
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: solemnwarning@solemnwarning.net.