-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.html
355 lines (303 loc) · 12.6 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>kexec-loader manual</title>
<style type="text/css">
<!--
body {
font-family: Arial, Helvetica, sans-serif;
}
h1, h1 a:hover {
font-size: xx-large;
color: #0099FF;
}
h2, h2 a:hover {
color: #0066FF;
}
h3, h3 a:hover {
color: #0033CC;
}
a:link, a:visited {
text-decoration: none;
color: blue;
}
a:hover {
color: red;
}
.code {
background-color: #E5E5E5;
border: 1px solid #000000;
padding: 5px;
font-family: monospace;
}
-->
</style>
</head>
<body>
<h1>kexec-loader manual</h1>
<p>Version: 2.2.1</p>
<p>Copyright © 2007-2011 Daniel Collins<br />Copyright © 2008-2009 Philip Kent</p>
<ul>
<li><a href="#s1">1. Introduction</a></li>
<li><a href="#s2">2. Usage</a>
<ul>
<li><a href="#s2s1">2.1. Basic Configuration</a></li>
<li><a href="#s2s2">2.2. Kernel Modules</a></li>
<li><a href="#s2s3">2.3. GRUB Configuration</a></li>
<li><a href="#s2s4">2.4. Changing the keymap</a></li>
<li><a href="#s2s5">2.5. Shell</a></li>
</ul>
</li>
<li><a href="#s3">3. Reference</a>
<ul>
<li><a href="#s3s1">3.1. Configuration Reference</a></li>
<li><a href="#s3s2">3.2. Shell Reference</a></li>
<li><a href="#s3s3">3.3. Kernel Command Line Options</a></li>
</ul>
</li>
<li><a href="#s4">4. Support</a>
<ul>
<li><a href="#s4s1">4.1. Website</a></li>
</ul>
</li>
</ul>
<h2><a name="s1">1. Introduction</a></h2>
<p>
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.
</p>
<p>
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.
</p>
<h2><a name="s2">2. Usage</a></h2>
<h3><a name="s2s1">2.1. Basic Configuration</a></h3>
<p>
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'.
</p>
<p class="code">
timeout 10<br />
<br />
title Generic Linux System (Kernel 2.6.20)<br />
root hda1<br />
kernel /boot/vmlinuz-2.6.20<br />
cmdline root=/dev/hda1 ro<br />
initrd /boot/initrd.img-2.6.20<br />
<br />
title Generic Linux System (Kernel 2.6.21)<br />
root hda1<br />
kernel /boot/vmlinuz-2.6.21<br />
cmdline root=/dev/hda1 ro<br />
initrd /boot/initrd.img-2.6.21<br />
default
</p>
<p>
It is also possible to reference files not on the root disk or filesystems by their volume label or UUID, as shown below.
</p>
<p class="code">
root <b>UUID=75ac0d6c-5dc0-402f-9f0f-9ab313816439</b><br />
initrd <b>(LABEL=otherdisk)</b>/boot/initrd.img-2.6.21
</p>
<h3><a name="s2s2">2.2. Kernel Modules</a></h3>
<p>
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 <a href="http://www.solemnwarning.net/kexec-loader/downloads/addmod.sh">addmod.sh</a> to insert it into the initramfs (initrd.img).
</p>
<p>
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:
</p>
<p class="code">
kmod module-name arg1 arg2=value arg3 ...
</p>
<p>
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.
</p>
<h3><a name="s2s3">2.3. GRUB Configuration</a></h3>
<p>
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:
</p>
<p class="code">
grub-path (hda1)/boot/grub
</p>
<p>
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:
</p>
<p class="code">
grub-map hd0 sda<br />
grub-map hd0,1 LABEL=root<br />
<br />
# BSD disklabels are not currently detected automatically<br />
#<br />
grub-map hd0,a sda8<br />
</p>
<h3><a name="s2s4">2.4. Changing the keymap</a></h3>
<p>
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 <a href="http://www.solemnwarning.net/kexec-loader/keymaps/">here</a> and save it to the boot disk as keymap.txt.
</p>
<h3><a name="s2s5">2.5. Shell</a></h3>
<p>
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:
</p>
<p class="code">
> root hda1<br />
> kernel /boot/vmlinuz-2.6.20<br />
> cmdline root=/dev/hda1 ro<br />
> initrd /boot/initrd.img-2.6.20<br />
> <b>boot</b>
</p>
<p>
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 <b>boot</b> 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.
</p>
<p>
The <b>ls</b> 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.
</p>
<p class="code">
> <b>ls</b> (fd0)/<br />
ldlinux.sys<br />
linux.cfg<br />
kexec-loader.conf<br />
syslinux.cfg<br />
README.html<br />
modules/<br />
initrd.img<br />
vmlinuz
</p>
<p>
The <b>find</b> 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.
</p>
<p class="code">
> <b>find</b> *linux* (fd0)/<br />
(fd0)/ldlinux.sys<br />
(fd0)/linux.cfg<br />
(fd0)/syslinux.cfg
</p>
<h2><a name="s3">3. Reference</a></h2>
<h3><a name="s3s1">3.1. Configuration Reference</a></h3>
<p>
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.
</p>
<p>
All valid configuration directives are listed below. Parameters are shown in <angled brackets> are required for that directive, ones in [square brackets] are optional.
</p>
<p>The following directives are global:</p>
<ul>
<li><b>timeout <off|integer></b><br />
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.
</li>
<li><b>grub-path <path></b><br />
Load device.map and grub.cfg/menu.lst from a GRUB installation at this directory. You must specify a device.
</li>
<li><b>grub-autodetect <on|off></b><br />
Enables or disables GRUB autodetection. Autodetection will be enabled by default if no boot targets are specified in kexec-loader.conf.
</li>
<li><b>grub-map <GRUB device> <device></b><br />
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.
</li>
<li><b>kmod <module> <args></b><br />
Set options to be passed to a kernel module if it is loaded.
</li>
</ul>
<p>The following directives are per-target:</p>
<ul>
<li><b>title <text></b><br />
Set the target title, all targets must begin with a title directive.
</li>
<li><b>root <device></b><br />
Set the root device, you must specify a root device, even if all paths specify their own device.
</li>
<li><b>kernel <path></b><br />
Path to the kernel, all targets must specify a kernel.
</li>
<li><b>initrd <path></b><br />
Path to an initrd/initramfs.
</li>
<li><b>cmdline <text></b><br />
Set the command line which will be passed to the target kernel.
</li>
<li><b>append <text></b><br />
Set the kernel command line using --append, this appears to do exactly
the same thing as cmdline, but is implemented for completeness.
</li>
<li><b>module <path> [args]</b><br />
Load and pass a multiboot module to the target kernel.
</li>
<li><b>default</b><br />
Mark this target as the default.
</li>
<li><b>reset-vga</b><br />
Reset the VGA adaptor before starting the kernel, may be useful if you get garbled or no output on bootup.
</li>
</ul>
<h3><a name="s3s2">3.2. Shell Reference</a></h3>
<p>
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.
</p>
<ul>
<li><b>root <device></b><br />
Set the root device, you must specify a root device to boot.
</li>
<li><b>kernel <path></b><br />
Path to the kernel, you must specify a kernel.
</li>
<li><b>initrd <path></b><br />
Path to an initrd/initramfs.
</li>
<li><b>cmdline <text></b><br />
Set the command line which will be passed to the target kernel.
</li>
<li><b>append <text></b><br />
Set the kernel command line using --append, this appears to do exactly
the same thing as cmdline, but is implemented for completeness.
</li>
<li><b>module <path> [args]</b><br />
Load and pass a multiboot module to the target kernel.
</li>
<li><b>reset-vga</b><br />
Reset the VGA adaptor before starting the kernel, may be useful if you get garbled or no output on bootup.
</li>
<li><b>boot</b><br />
Boot the system using settings entered in the shell.
</li>
<li><b>disks</b><br />
Display a list of disks and partitions which have been detected by Linux.
</li>
<li><b>ls <directory></b><br />
List the contents of a directory.
</li>
<li><b>find <filename> <directory></b><br />
Search a directory for files matching the pattern 'filename', filename may include the wildcard characters * or ?.
</li>
<li><b>cat <filename></b><br />
Print the contents of a file to the console.
</li>
<li><b>exit</b>
<br />Leave the shell and go back to the menu.
</li>
</ul>
<h3><a name="s3s3">3.3. Kernel Command Line Options</a></h3>
<p>
The following options can be passed to kexec-loader via the kernel command line.
</p>
<ul>
<li><b>boot_index</b><br />
Automatically boot a target by it's index number (starting at 0).
</li>
<li><b>boot_target</b><br />
Automatically boot a target by it's title. This is ignored if boot_index is also supplied.
</li>
<li><b>root</b><br />
Sets the kexec-loader boot disk. The default is LABEL=kexecloader.
</li>
<li><b>rootdir</b><br />
Set the directory containing the kexec-loader files.
</li>
<li><b>debug_tty</b><br />
Set the terminal/file to write debug messages to. Default is /dev/tty3.
</li>
</ul>
<h2><a name="s4">4. Support</a></h2>
<h3><a name="s4s1">4.1. Website</a></h3>
<p>
For information on kexec-loader, including current development and latest
releases, please see the project <a href="http://www.solemnwarning.net/kexec-loader/">website</a>.
</p>
</body>
</html>