kexec-loader manual

Version: 2.3

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

• 1. Introduction
• 2. Usage
  • 2.1. Basic Configuration
  • 2.2. Kernel Modules
  • 2.3. GRUB Configuration
  • 2.4. Changing the keymap
  • 2.5. Shell
• 3. Reference
  • 3.1. Configuration Reference
  • 3.2. Shell Reference
  • 3.3. Kernel Command Line Options
• 4. Support
  • 4.1. Website

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
default

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 addmod.sh 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)/
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

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:

• timeout <off|integer>
  Number of seconds to wait at the menu screen before booting the default target, the first target will be booted if none are marked as default. The default is "off" which will make the menu wait forever.
• grub-path <path>
  Load device.map and grub.cfg/menu.lst from a GRUB installation at this directory. You must specify a device.
• grub-autodetect <on|off>
  Enables or disables GRUB autodetection. Autodetection will be enabled by default if no boot targets are specified in kexec-loader.conf.
• grub-map <GRUB device> <device>
  Map a GRUB device name. Whole disks or partitions may be mapped, filesystem UUIDs and labels are allowed when mapping partitions. BSD disklabels must be mapped in order to be used from the GRUB configuration.
• 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.

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.

• 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.

3.3. Kernel Command Line Options

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

• boot_index
  Automatically boot a target by it's index number (starting at 0).
• boot_target
  Automatically boot a target by it's title. This is ignored if boot_index is also supplied.
• root
  Sets the kexec-loader boot disk. The default is LABEL=kexecloader.
• rootdir
  Set the directory containing the kexec-loader files.
• debug_tty
  Set the terminal/file to write debug messages to. Default is /dev/tty3.

4. Support

4.1. Website

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