Version: 2.2.2
Copyright © 2007-2010 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.
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.
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
If there is only one GRUB installation on the system you can use autodetection rather than manually entering the GRUB directory, if autodetection is enabled the first GRUB installation found will be used. This cannot be used if grub-path is defined.
grub-autodetect on
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.
If you need to add modules to the initramfs, there is a bash script available which will decompress, extract and copy the modules to the initramfs. Modules are decompressed and extracted before being added to the initramfs to maximise the compression of the initramfs file. The script is named addmod.sh and is available in the kexec-loader source archive, it can also be downloaded here: addmod.sh.
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(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:
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.
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.