1 |
<?xml version='1.0' encoding="UTF-8"?> |
2 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/genkernel.xml,v 1.17 2005/07/24 16:51:15 plasmaroo Exp $ --> |
3 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
4 |
|
5 |
<guide link="/doc/en/genkernel.xml"> |
6 |
<title>Gentoo Linux Genkernel Guide</title> |
7 |
|
8 |
<author title="Author"> |
9 |
<mail link="plasmaroo@gentoo.org">Tim Yamin</mail> |
10 |
</author> |
11 |
|
12 |
<!-- folajimi@speakeasy.net --> |
13 |
<author title="Contributor"> |
14 |
Jimi Ayodele |
15 |
</author> |
16 |
|
17 |
<!-- thseiler@gmail.com --> |
18 |
<author title="NFS Support"> |
19 |
Thomas Seiler |
20 |
</author> |
21 |
|
22 |
<abstract> |
23 |
This guide intends to provide a reference of all the functions provided by |
24 |
genkernel. |
25 |
</abstract> |
26 |
|
27 |
<license/> |
28 |
|
29 |
<version>1.3</version> |
30 |
<date>July 24, 2005</date> |
31 |
|
32 |
<chapter> |
33 |
<title>Introduction</title> |
34 |
<section> |
35 |
<title>Rationale</title> |
36 |
<body> |
37 |
|
38 |
<p> |
39 |
For users who are not privy to kernel compilation, genkernel is a tool to |
40 |
automate this process. It can help you create a kernel image akin to those |
41 |
available on Gentoo Installation CDs, which are designed to auto-detect the |
42 |
hardware configuration of your system. Some users may also be interested in |
43 |
using genkernel for hardware requiring initialization and a working kernel |
44 |
before the system starts up. Since genkernel automatically compiles your kernel |
45 |
modules, you can use hardware that may require certain module parameters to be |
46 |
loaded for proper operation. |
47 |
</p> |
48 |
|
49 |
</body> |
50 |
</section> |
51 |
|
52 |
<section> |
53 |
<title>Target Audience</title> |
54 |
<body> |
55 |
|
56 |
<p> |
57 |
If you are either uncertain about how to compile a kernel, or are just |
58 |
unfamiliar with your hardware configuration, genkernel is a very handy tool. |
59 |
It is designed to take the pain out of the kernel compiling process, and |
60 |
supports most hardware by default. |
61 |
</p> |
62 |
|
63 |
<p> |
64 |
However, if you know what drivers are required by your system, you may be able |
65 |
to further reduce the time taken to compile the kernel. This is possible since |
66 |
you can direct genkernel to only build drivers relevant to your hardware. |
67 |
Oftentimes, the number of drivers required by your system will be fewer |
68 |
(implying a shorter kernel compilation time) than the default configuration |
69 |
provides. |
70 |
</p> |
71 |
|
72 |
</body> |
73 |
</section> |
74 |
<section> |
75 |
<title>Installing genkernel</title> |
76 |
<body> |
77 |
|
78 |
<p> |
79 |
To obtain genkernel, run <c>emerge genkernel</c> from the command line. If you |
80 |
are using the |
81 |
<uri link="http://www.gentoo.org/doc/en/handbook/2005.0/hb-install-about.xml#doc_chap2_sect1"> |
82 |
Gentoo Reference Platform</uri> (GRP), remember to install binary packages by |
83 |
passing the <c>-k</c> flag to emerge. Since the GRP is bundled with an older |
84 |
version of genkernel, the flags may be different. In any case, consult |
85 |
<c>genkernel --help</c> for help on how to use the version of genkernel |
86 |
installed on your system. |
87 |
</p> |
88 |
|
89 |
</body> |
90 |
</section> |
91 |
</chapter> |
92 |
|
93 |
<chapter> |
94 |
<title>Working with genkernel</title> |
95 |
<section> |
96 |
<title>How to use genkernel</title> |
97 |
<body> |
98 |
|
99 |
<p> |
100 |
Although there are several ways to run genkernel, the least-intrusive approach |
101 |
is provided by <c>genkernel all</c>. Here, a generic configuration which works |
102 |
well for most systems is used. As was mentioned earlier, this approach is not |
103 |
without drawbacks; most of the modules created are useless to the average user |
104 |
and may increase compile time. Below is an illustration of a more efficient |
105 |
approach, achieved by passing certain flags to genkernel as root: |
106 |
</p> |
107 |
|
108 |
<pre caption="Running genkernel (with flags)"> |
109 |
# genkernel --bootsplash --no-install --no-clean --menuconfig all |
110 |
</pre> |
111 |
|
112 |
<p> |
113 |
The above operation causes genkernel to create a bootsplash-enabled kernel |
114 |
(<c>--bootsplash</c>) that will have to be manually installed |
115 |
(<c>--no-install</c>). While preparing the kernel source tree, genkernel will |
116 |
refrain from cleaning out any preexisting object files present in the source |
117 |
tree (<c>--no-clean</c>). A menu-driven kernel configuration utility will be |
118 |
displayed that allows the user to select which modules will be built for the |
119 |
system (<c>--menuconfig</c>). |
120 |
</p> |
121 |
|
122 |
<p> |
123 |
There are other flags which alter the result provided by genkernel. For |
124 |
instance, replacing <c>--no install</c> with the <c>--install</c> flag allows |
125 |
genkernel to automatically install the new kernel in the <path>/boot</path> |
126 |
directory. Using the <c>--mountboot</c> flag allows genkernel to mount your |
127 |
<path>/boot</path> partition automatically, if necessary. |
128 |
</p> |
129 |
|
130 |
<p> |
131 |
Remember, genkernel is designed to make kernel compilation easy and |
132 |
stress-free. For this reason, genkernel features several flags to ease the |
133 |
kernel compilation effort. For example, there are flags to help with kernel |
134 |
configuration, while others affect the actual compilation. Some flags even help |
135 |
debug the compilation process. For those interested in further optimization, |
136 |
there are flags that affect kernel assembling, packaging and even kernel |
137 |
initialization. |
138 |
</p> |
139 |
|
140 |
<p> |
141 |
The rest of this chapter examines the functionality of various flags and |
142 |
actions available for genkernel. Some of the flags have variants which perform |
143 |
a converse operation. The converse variants carry the <b><c>no-</c></b> prefix, |
144 |
and their effects are enclosed within the square brackets, []. |
145 |
</p> |
146 |
|
147 |
</body> |
148 |
</section> |
149 |
|
150 |
<section> |
151 |
<title>Configuration Flags</title> |
152 |
<body> |
153 |
|
154 |
<p> |
155 |
The configuration flags listed below exist to help you decide what features |
156 |
should be enabled or disabled in the kernel prior to compilation. You can even |
157 |
choose whether or not the configuration file created in the process should be |
158 |
saved. The following are the primary configuration flags: |
159 |
</p> |
160 |
|
161 |
<ul> |
162 |
<li> |
163 |
<b>--<c>no-</c>menuconfig</b>: Activates <e>[or deactivates]</e> the |
164 |
<c>make menuconfig</c> command (which invokes an interactive, menu-based |
165 |
kernel configuration utility), before building the kernel. |
166 |
</li> |
167 |
<li> |
168 |
<b>--gconfig</b>: Provides a kernel configuration utility which depends |
169 |
on the GTK+ libraries. The advantage of this option is that most users |
170 |
find it easier and clearer to configure the kernel using this tool, since |
171 |
it relies on the X-windowing system. The disadvantage of this option is |
172 |
that you <b>need</b> the X-windowing system to use it, so it will not |
173 |
work on the command line. |
174 |
</li> |
175 |
<li> |
176 |
<b>--xconfig</b>: Provides a kernel configuration utility which depends |
177 |
on the QT libraries. The advantage of this option is that most users find |
178 |
it easier and clearer to configure the kernel using this tool, since it |
179 |
relies on the X-windowing system. The disadvantage of this option is that |
180 |
you <b>need</b> the X-windowing system to use it, so it will not work on |
181 |
the command line. |
182 |
</li> |
183 |
<li> |
184 |
<b>--<c>no-</c>save-config</b>: Saves [or does not save] the kernel |
185 |
configuration to a file in the <path>/etc/kernels/</path> directory for |
186 |
later use. |
187 |
</li> |
188 |
</ul> |
189 |
|
190 |
</body> |
191 |
</section> |
192 |
|
193 |
<section> |
194 |
<title>Compilation Flags</title> |
195 |
<body> |
196 |
|
197 |
<p> |
198 |
The following flags usually take effect during the actual compilation: |
199 |
</p> |
200 |
|
201 |
<ul> |
202 |
<li> |
203 |
<b>--kerneldir=<path>/path/to/sources/</path></b>: Specifies an |
204 |
alternative kernel source location, rather than the default |
205 |
<path>/usr/src/linux/</path> location. |
206 |
</li> |
207 |
<li> |
208 |
<b>--kernel-config=<path>/path/to/config-file</path></b>: Specifies what |
209 |
alternative kernel configuration will be used, rather than the default |
210 |
<path>/path/to/sources/.config</path> file. |
211 |
</li> |
212 |
<li> |
213 |
<b>--module-prefix=<path>/path/to/prefix-directory/</path></b>: Specifies |
214 |
a prefix to the directory where kernel modules will be installed (default |
215 |
path is the <path>/lib/modules/</path> directory.) |
216 |
</li> |
217 |
</ul> |
218 |
|
219 |
<ul> |
220 |
<li> |
221 |
<b>--<c>no-</c>clean</b>: Activates <e>[or deactivates]</e> the |
222 |
<c>make clean</c> command before compiling your kernel. The |
223 |
<c>make clean</c> command removes all object files and dependencies from |
224 |
the kernel's source tree. |
225 |
</li> |
226 |
<li> |
227 |
<b>--<c>no-</c>mrproper</b>: Activates <e>[or deactivates]</e> the |
228 |
<c>make mrproper</c> command before kernel compilation. Like the |
229 |
<c>make clean</c> command, <c>make mrproper</c> removes all object files |
230 |
and dependencies from the kernel's source tree. However, any previous |
231 |
configuration files (in <path>/path/to/sources/.config</path> or |
232 |
<path>/path/to/sources/.config.old</path>) will <b>also</b> be purged |
233 |
from the kernel's source tree. |
234 |
</li> |
235 |
<li> |
236 |
<b>--oldconfig</b>: Issues the <c>make oldconfig</c> command, which |
237 |
attempts to collect configuration information for the system's |
238 |
architecture from a generic script in <path>/usr/share/genkernel/</path>. |
239 |
This is a non-interactive process; no user input is entertained. Also, if |
240 |
<c>--oldconfig</c> is used in conjunction with <c>--clean</c>, the latter |
241 |
flag is negated, resulting in the activation of the <c>--no-clean</c> |
242 |
flag. |
243 |
</li> |
244 |
</ul> |
245 |
|
246 |
<ul> |
247 |
<li> |
248 |
<b>--callback="<c>echo hello</c>"</b>: Calls the specified arguments |
249 |
(<c>echo hello</c>, in this case) after the kernel and the relevant |
250 |
modules have been built, but before building the initrd image. This may |
251 |
be useful if you want to install external modules in the initrd image by |
252 |
emerging the relevant item(s) with the callback feature, and then |
253 |
redefining a genkernel module group. |
254 |
</li> |
255 |
</ul> |
256 |
|
257 |
<ul> |
258 |
<li> |
259 |
<b>--<c>no-</c>install</b>: Activates <e>[or deactivates]</e> the |
260 |
<c>make install</c> command, which installs your new kernel image, |
261 |
configuration file, initrd image and system map onto your mounted boot |
262 |
partition. Any compiled modules will be installed as well. |
263 |
</li> |
264 |
<li> |
265 |
<b>--<c>no-</c>initrdmodules</b>: Refrains from copying any modules to |
266 |
the genkernel-created initrd image. This flag is an exception to the rule |
267 |
about the <c>no-</c> prefix; omission of this prefix creates an invalid |
268 |
genkernel flag. |
269 |
</li> |
270 |
<li> |
271 |
<b>--genzimage</b>: Creates the initrd image, prior to the kernel image. |
272 |
(This hack currently applies only to PPC Pegasos systems.) |
273 |
</li> |
274 |
</ul> |
275 |
|
276 |
</body> |
277 |
</section> |
278 |
|
279 |
<section> |
280 |
<title>Compiler Flags</title> |
281 |
<body> |
282 |
|
283 |
<p> |
284 |
The following flags are supported by genkernel, and are passed to the relevant |
285 |
applications while the kernel is being assembled. These flags affect the |
286 |
<e>compiler</e> used for the kernel compilation process, albeit at a much lower |
287 |
level. |
288 |
</p> |
289 |
|
290 |
<ul> |
291 |
<li> |
292 |
<b>--kernel-cc=<c>someCompiler</c></b>: Specifies the compiler employed |
293 |
during the kernel compilation process. |
294 |
</li> |
295 |
<li> |
296 |
<b>--kernel-ld=<c>someLinker</c></b>: Specifies the linker employed |
297 |
during the kernel compilation process. |
298 |
</li> |
299 |
<li> |
300 |
<b>--kernel-as=<c>someAssembler</c></b>: Specifies the assembler employed |
301 |
during the kernel compilation process. |
302 |
</li> |
303 |
<li> |
304 |
<b>--kernel-make=<c>someMake</c></b>: Specifies an alternative to the |
305 |
<e>GNU make</e> utility employed during the kernel compilation process. |
306 |
</li> |
307 |
</ul> |
308 |
|
309 |
<ul> |
310 |
<li> |
311 |
<b>--utils-cc=<c>someCompiler</c></b>: Specifies the compiler employed |
312 |
during the compilation of support utilities. |
313 |
</li> |
314 |
<li> |
315 |
<b>--utils-ld=<c>someLinker</c></b>: Specifies the linker employed during |
316 |
the compilation of support utilities. |
317 |
</li> |
318 |
<li> |
319 |
<b>--utils-as=<c>someAssembler</c></b>: Specifies the assembler employed |
320 |
during the compilation of support utilities. |
321 |
</li> |
322 |
<li> |
323 |
<b>--utils-make=<c>someMake</c></b>: Specifies an alternative to the |
324 |
<e>GNU make</e> utility employed during the compilation of support |
325 |
utilities. |
326 |
</li> |
327 |
</ul> |
328 |
|
329 |
<ul> |
330 |
<li> |
331 |
<b>--makeopts=<c>-jX</c></b>: Specifies the number of concurrent threads |
332 |
that the make utility can implement while the kernel (and utilities) are |
333 |
being compiled. The variable <b>'X'</b> is a number obtained by adding |
334 |
one (1) to the number of CPUs used by the system. So, for a system with |
335 |
one CPU, the appropriate flag is <c>-j2</c>; a system with two CPUs will |
336 |
use the <c>-j3</c> flag, and so on. <e>(A system with one processor that |
337 |
supports Hyper-Threading™ (HT) Technology can use the</e><c>-j3</c> |
338 |
<e>flag, provided Symmetric Multi-Processing (SMP) support is enabled in |
339 |
the kernel.)</e> |
340 |
</li> |
341 |
</ul> |
342 |
|
343 |
</body> |
344 |
</section> |
345 |
|
346 |
<section> |
347 |
<title>Debugging Flags</title> |
348 |
<body> |
349 |
|
350 |
<p> |
351 |
The use debugging flags during the kernel compilation process controls the |
352 |
amount of information reported, as well as the presentation of said data. |
353 |
</p> |
354 |
|
355 |
<ul> |
356 |
<li> |
357 |
<b>--debuglevel=<c>verblevel</c></b>: Controls the level of |
358 |
verbosity for information provided by genkernel. The variable |
359 |
<c>verblevel</c> is an integer between 0 and 5. The level '0' represents |
360 |
minimal output, while '5' provides as much information as possible about |
361 |
genkernel's activities during the kernel compilation process. |
362 |
</li> |
363 |
<li> |
364 |
<b>--debugfile=<path>/path/to/outputfile</path></b>: Ignores the value |
365 |
set by the <c>--debuglevel</c> argument, and sends <b>all</b> debugging |
366 |
data produced by genkernel to the specified output file, which is located |
367 |
at <path>/var/log/genkernel.log</path> by default. |
368 |
</li> |
369 |
<li> |
370 |
<b>--no-color</b>: Activates [or deactivates] colored output of debugging |
371 |
information (reported by genkernel) using escape sequences. |
372 |
</li> |
373 |
</ul> |
374 |
|
375 |
</body> |
376 |
</section> |
377 |
|
378 |
<section> |
379 |
<title>Initialization Flags</title> |
380 |
<body> |
381 |
|
382 |
<p> |
383 |
The flags here are used to create certain effects during system startup. Some |
384 |
of these flags are primarily for aesthetics, while others may be essential for |
385 |
enabling certain features on the system. |
386 |
</p> |
387 |
|
388 |
<ul> |
389 |
<li> |
390 |
<b>--<c>no-</c>bootsplash</b>: Activates <e>[or deactivates]</e> support |
391 |
for <uri link="http://www.bootsplash.org/">bootsplash</uri> in the |
392 |
genkernel-built initrd image. The bootsplash feature is supported on a |
393 |
limited number of architectures, and a kernel that supports bootsplash |
394 |
is also required. |
395 |
</li> |
396 |
<li> |
397 |
<b>--<c>no-</c>gensplash</b>: Activates <e>[or deactivates]</e> support |
398 |
for <uri link="http://dev.gentoo.org/~spock/projects/gensplash/">gensplash</uri> |
399 |
support in the genkernel-built initrd image. The gensplash utility is |
400 |
intended to be a replacement for bootsplash, and is designed for use with |
401 |
2.6.x series kernels. To override the default theme used by gensplash, |
402 |
use <b>--gensplash=<c>PreferredTheme</c></b> (where <c>PreferredTheme</c> |
403 |
is the title of one of the directories inside the |
404 |
<path>/etc/splash/</path> directory. |
405 |
</li> |
406 |
<li> |
407 |
<b>--gensplash-res=<c>PreferredResolution</c></b>: This flag allows you |
408 |
to select which splash screen resolutions will be supported in the initrd |
409 |
during the start-up of the system. This is useful for two reasons: First, |
410 |
you are able to select only the splash screen resolution(s) relevant to |
411 |
your system. Second, you avoid the unnecessary increase in the disk space |
412 |
required by initrd (since the initrd does not have to support resolutions |
413 |
that are irrelevant for your system configuration.) However, you may want |
414 |
to omit this flag if the kernel is being compiled for an Installation CD; |
415 |
this allows gensplash support for all possible resolutions. |
416 |
</li> |
417 |
<li> |
418 |
<b>--do-keymap-auto</b>: Force keymap selection during the boot |
419 |
sequence. |
420 |
</li> |
421 |
<li> |
422 |
<b>--lvm2</b>: Includes support for storage using via <uri |
423 |
link="http://sources.redhat.com/lvm2/">Logical Volume Management</uri> |
424 |
(LVM2) from <e>static</e> binaries, if available to the system. Relevant |
425 |
(static) LVM2 binaries are compiled if they are unavailable. Be sure to |
426 |
install the lvm2 package on your system with <c>emerge lvm2</c> before |
427 |
enabling this flag, and review the <uri |
428 |
link="http://www.gentoo.org/doc/en/lvm2.xml">Gentoo LVM2 |
429 |
Installation</uri> guide. |
430 |
</li> |
431 |
<li> |
432 |
<b>--evms2</b>: Includes support for storage using the <uri |
433 |
link="http://evms.sourceforge.net/">Enterprise Volume Management |
434 |
System</uri> (EVMS2), if available. Be sure to install the evms package |
435 |
on your system with <c>USE=static emerge evms2</c> before using this |
436 |
(genkernel) flag. <e>(Omitting the </e><c>USE=static</c> <e>flag during |
437 |
package installation will fail to include the necessary static binaries.) |
438 |
</e> |
439 |
</li> |
440 |
<li> |
441 |
<b>--dmraid</b>: Includes support for <uri |
442 |
link="http://people.redhat.com/~heinzm/sw/dmraid/readme">DMRAID</uri>; |
443 |
the utility which creates RAID mappings using the kernel device-mapper |
444 |
subsystem. DMRAID discovers, activates, deactivates and displays |
445 |
properties of software RAID sets (ATARAID, for example) and contained |
446 |
DOS partitions. |
447 |
</li> |
448 |
<li> |
449 |
<b>--linuxrc=/path/to/your/linuxrc</b>: Specifies a user-created |
450 |
<e>linuxrc</e> — a script that is initialized during the start-up |
451 |
stage of the kernel, prior to the actual boot process. (A default linuxrc |
452 |
script should be in the <path>/usr/share/genkernel/</path> directory.) |
453 |
This script allows you to boot into a small, modularized kernel and load |
454 |
the drivers that are needed (as modules) by the system. |
455 |
</li> |
456 |
<li> |
457 |
<b>--cachedir=/path/to/alt/dir/</b>: Overrides the default cache location |
458 |
used while compiling the kernel. |
459 |
</li> |
460 |
<li> |
461 |
<b>--tempdir=/path/to/new/tempdir/</b>: Specifies the location of the |
462 |
temporary directory used by genkernel while compiling the kernel. |
463 |
</li> |
464 |
<li> |
465 |
<b>--unionfs</b>: Includes support for the <uri |
466 |
link="http://www.fsl.cs.sunysb.edu/project-unionfs.html">Unification File |
467 |
System</uri> in the initrd image. |
468 |
</li> |
469 |
</ul> |
470 |
|
471 |
</body> |
472 |
</section> |
473 |
|
474 |
<section> |
475 |
<title>Miscellaneous Flags</title> |
476 |
<body> |
477 |
|
478 |
<p> |
479 |
The assortment of flags listed below are supported by genkernel, but do not fit |
480 |
neatly into any of the other categories: |
481 |
</p> |
482 |
|
483 |
<ul> |
484 |
<li> |
485 |
<b>--mountboot</b>: Detects whether or not the <path>/boot/</path> |
486 |
directory needs to be mounted on a separate partition. It will check |
487 |
<path>/etc/fstab</path> script for instructions on how to mount the boot |
488 |
partition on a file system (if needed). |
489 |
</li> |
490 |
<li> |
491 |
<b>--kernname=<c>NickName</c></b>: Allows you to modify the name of the |
492 |
kernel and initrd images in the <path>/boot/</path> directory, so that |
493 |
the images produced are kernel-<c>NickName</c>-version and |
494 |
initramfs-<c>NickName</c>-version. |
495 |
</li> |
496 |
</ul> |
497 |
|
498 |
</body> |
499 |
</section> |
500 |
|
501 |
|
502 |
<section> |
503 |
<title>Possible Actions</title> |
504 |
<body> |
505 |
|
506 |
<p> |
507 |
An action tells genkernel what to build. Currently, the following actions are |
508 |
supported: |
509 |
</p> |
510 |
|
511 |
<ul> |
512 |
<li><c>initrd</c>: Only builds the initrd image</li> |
513 |
<li><c>bzImage</c>: Only builds the kernel image</li> |
514 |
<li><c>kernel</c>: Only builds the kernel image and modules</li> |
515 |
<li><c>all</c>: Builds all stages — the initrd, kernel image and |
516 |
modules.</li> |
517 |
</ul> |
518 |
|
519 |
<p> |
520 |
The last action, <c>all</c>, is recommended for most users since it builds the |
521 |
stages required for a functional kernel. Remember, an <e>action</e> simply |
522 |
tells genkernel what to <e>build</e>, not <e>install</e>. |
523 |
</p> |
524 |
|
525 |
</body> |
526 |
</section> |
527 |
|
528 |
|
529 |
<section> |
530 |
<title>Bootloader Configuration</title> |
531 |
<body> |
532 |
|
533 |
<p> |
534 |
To set up genkernel to work with your bootloader, three or four changes should |
535 |
to the bootloader's configuration file: |
536 |
</p> |
537 |
|
538 |
<ol> |
539 |
<li> |
540 |
Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the kernel |
541 |
parameters passed to the kernel image. |
542 |
</li> |
543 |
<li> |
544 |
Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters |
545 |
passed to the kernel image, if <path>/dev/hda3</path> contains your root |
546 |
partition. |
547 |
</li> |
548 |
<li> |
549 |
If you are using bootsplash, add a suitable mode line such as |
550 |
<c>vga=0x317</c> to the parameters passed to the kernel and also add |
551 |
<c>splash=verbose</c> or <c>splash=silent</c> depending on the |
552 |
verboseness you require from your bootloader. |
553 |
</li> |
554 |
<li> |
555 |
Add the initrd information as required by the bootloader. Consult the |
556 |
<uri link="/doc/en/handbook/handbook-x86.xml?part=1&chap=10"> |
557 |
Bootloader Configuration Chapter</uri> of the Gentoo Handbook for details |
558 |
on how to make your bootloader initrd-aware. |
559 |
</li> |
560 |
</ol> |
561 |
|
562 |
</body> |
563 |
</section> |
564 |
|
565 |
</chapter> |
566 |
|
567 |
<chapter> |
568 |
<title>Configuration Options</title> |
569 |
|
570 |
<section> |
571 |
<title>Editing /etc/genkernel.conf</title> |
572 |
<body> |
573 |
|
574 |
<p> |
575 |
Passing flags to genkernel from the command line can be cumbersome, especially |
576 |
if you have about a dozen flags: |
577 |
</p> |
578 |
|
579 |
<pre caption="Running genkernel (overloaded with flags)"> |
580 |
# genkernel --debuglevel=5 --no-color --no-mrproper --clean --gensplash\ |
581 |
--kerneldir=/path/to/alternate/kernel/sources --install --menuconfig --udev\ |
582 |
--kernel-config=/path/to/preferred/configfile --save-config --mountboot all |
583 |
</pre> |
584 |
|
585 |
<p>Fortunately, there is a configuration file where most of the basic options |
586 |
can be set (or changed) as necessary. What follows is a rundown of the more |
587 |
relevant options: |
588 |
</p> |
589 |
|
590 |
<ul> |
591 |
<li> |
592 |
<b>MENUCONFIG=<c>[yes|no]</c></b>: This option is equivalent to the |
593 |
<c>--menuconfig</c> flag used by genkernel, which in turn uses the |
594 |
<c>make menuconfig</c> command to invoke a command-line based kernel |
595 |
configuration utility. To invoke the utility automatically during kernel |
596 |
configuration via this script, set this option to 'yes' here; otherwise, |
597 |
choose 'no'. |
598 |
</li> |
599 |
<li> |
600 |
<b>CLEAN=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent |
601 |
to the <c>--clean</c> flag used by genkernel, and invokes the |
602 |
<c>make clean</c> command to remove all object files and dependencies |
603 |
from the kernel's source tree. Setting this option to 'no' creates a |
604 |
cascade effect — it is equivalent to genkernel's <c>--no-clean</c> |
605 |
flag, which disables the <c>make clean</c> command and implies |
606 |
genkernel's <c>--no-mrproper</c> flag — essentially nullifying the |
607 |
<c>make mrproper</c> command. |
608 |
</li> |
609 |
<li> |
610 |
<b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is |
611 |
equivalent to <c>--mrproper</c> flag used by genkernel, and invokes the |
612 |
<c>make mrproper</c> command, which purges the kernel source tree of any |
613 |
configuration files. Selecting 'no' here is equivalent to genkernel's |
614 |
<c>--no-mrproper</c> flag, which disables the <c>make mrproper</c> |
615 |
command. |
616 |
</li> |
617 |
<li> |
618 |
<b>MOUNTBOOT=<c>[yes|no]</c></b>: Setting this option to 'yes' is |
619 |
equivalent to the <c>--mountboot</c> flag, and automatically mounts the |
620 |
<path>/boot/</path> directory (if needed) at compile time. If the |
621 |
<path>/boot/</path> directory is on a separate partition, consider |
622 |
enabling this option; it will make for one less (essential) step to |
623 |
remember later. |
624 |
</li> |
625 |
<li> |
626 |
<b>SAVE_CONFIG=<c>[yes|no]</c></b>: After configuring the kernel, the |
627 |
selected options are stored as <path>.config</path> in the kernel source |
628 |
tree. This script may be overwritten during the next kernel compilation, |
629 |
or even purged from the kernel source tree. Choosing 'yes' here is |
630 |
equivalent to the <c>--save-config</c> flag, and stores all options |
631 |
selected during kernel configuration as a script in the |
632 |
<path>/etc/kernels/</path> directory. Choosing 'no' preserves the |
633 |
<e>status quo</e>. |
634 |
</li> |
635 |
<li> |
636 |
<b>USECOLOR=<c>[yes|no]</c></b>: Setting this option to 'yes' is |
637 |
equivalent to the <c>--color</c> flag, which colors genkernel's output |
638 |
to ease debugging (when needed.) |
639 |
</li> |
640 |
<li> |
641 |
<b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the |
642 |
verbosity of the output produced by genkernel — setting this option |
643 |
to '0' with <c>--debuglevel=0</c> will suppress all output produced by |
644 |
genkernel; setting this option to '5' with <c>--debuglevel=5</c> |
645 |
provides the user with all output produced by genkernel. |
646 |
</li> |
647 |
</ul> |
648 |
|
649 |
<p> |
650 |
By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you |
651 |
can halve the number of flags passed to genkernel from the command line: |
652 |
</p> |
653 |
|
654 |
<pre caption="Running genkernel (with flags), after employing genkernel.conf"> |
655 |
# genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources --udev\ |
656 |
--kernel-config=/path/to/preferred/configfile --install all |
657 |
</pre> |
658 |
|
659 |
<p> |
660 |
Identical results are obtained from both approaches, but the latter has most of |
661 |
the options stored in a script that can be modified at a later date. |
662 |
</p> |
663 |
|
664 |
</body> |
665 |
</section> |
666 |
|
667 |
</chapter> |
668 |
|
669 |
<chapter> |
670 |
<title>Network-Booting with genkernel</title> |
671 |
|
672 |
<section> |
673 |
<title>Network Booting from an Installation CD</title> |
674 |
<body> |
675 |
|
676 |
<p> |
677 |
The genkernel utility can build kernel and initrd images that provide support |
678 |
for network booting, or <e>netboot</e>ing . With any luck, you should be able |
679 |
to netboot any recent computer into the environment provided by the |
680 |
Installation CD. |
681 |
</p> |
682 |
|
683 |
<p> |
684 |
The magic lies in genkernel's linuxrc script: it will try to <e>netmount</e> |
685 |
the Installation CD using NFS. From there, <e>the init scripts</e> of the |
686 |
Installation CD can take over, as if the CD was present locally. |
687 |
</p> |
688 |
|
689 |
</body> |
690 |
</section> |
691 |
|
692 |
<section> |
693 |
<title>Building Kernel and Initrd Images with Support for Netbooting</title> |
694 |
<body> |
695 |
|
696 |
<p> |
697 |
To enable support for netbooting, include the following options while |
698 |
configuring the kernel: |
699 |
</p> |
700 |
|
701 |
<warn> |
702 |
Support for netbooting with genkernel is experimental and may contain bugs. |
703 |
</warn> |
704 |
|
705 |
<p> |
706 |
First, the kernel image must include the drivers for your Network Interface |
707 |
Cards (NIC). Normally, drivers for such devices will be compiled as modules. |
708 |
However, it is essential (for netbooting) that you such drivers compiled |
709 |
directly into the kernel image and <b>not</b> as modules. |
710 |
</p> |
711 |
|
712 |
<pre caption="Configuring a 2.6.x series kernel to support your NIC driver"> |
713 |
Device Drivers ---> |
714 |
Networking Support ---> |
715 |
Ethernet (10 or 100Mbit) ---> |
716 |
[*] Ethernet (10 or 100Mbit) |
717 |
<*> the driver for your network card |
718 |
<comment>(Be sure to select <*> and not <m>)</comment> |
719 |
</pre> |
720 |
|
721 |
<p> |
722 |
Secondly, we suggest that you enable <c>IP: kernel level |
723 |
autoconfiguration</c> and the <c>IP: DHCP support</c> options. This avoids an |
724 |
unnecessary layer of complexity since the IP address and the NFS path to the |
725 |
Installation CD can be configured on a DHCP server. Of course, this means the |
726 |
kernel command line will remain constant for any machine — which is very |
727 |
important for <e>etherbooting</e>. |
728 |
</p> |
729 |
|
730 |
<pre caption="Configuring a 2.6.x series kernel to support DHCP"> |
731 |
Device Drivers ---> |
732 |
Networking Support ---> |
733 |
Networking options |
734 |
[*] TCP/IP networking---> |
735 |
[*] IP: kernel level autoconfiguration |
736 |
[*] IP: DHCP support |
737 |
<comment>(These options tell the kernel to send a DHCP request at bootup.)</comment> |
738 |
</pre> |
739 |
|
740 |
<p> |
741 |
Additionally, you should enable SquashFS because most modern Gentoo |
742 |
Installation CDs require it. Support for SquashFS is not included with the |
743 |
generic kernel source tree. To enable SquashFS, apply the necessary patches to |
744 |
the generic kernel source or install <c>gentoo-sources</c>. |
745 |
</p> |
746 |
|
747 |
<pre caption="Configuring the kernel to support SquashFS"> |
748 |
File systems---> |
749 |
Miscellaneous filesystems ---> |
750 |
[*] SquashFS 2.X - Squashed file system support |
751 |
</pre> |
752 |
|
753 |
<p> |
754 |
Once the compilation process is completed, create a compressed <e>tarball</e> |
755 |
(tar.gz) that contains the kernel's modules. This step is only necessary if |
756 |
your kernel version does not match the kernel image version on the Installation |
757 |
CD. |
758 |
</p> |
759 |
|
760 |
<pre caption="Creating a compressed tarball containing the kernel modules"> |
761 |
<comment># Create a tar.gz containing all the modules</comment> |
762 |
cd / |
763 |
tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/ |
764 |
</pre> |
765 |
|
766 |
<p> |
767 |
Depending on your network boot mechanism, you will need to do some of the |
768 |
following steps: |
769 |
</p> |
770 |
|
771 |
<pre caption="Creating a boot image"> |
772 |
<comment># Create a etherboot image</comment> |
773 |
emerge mknbi |
774 |
cd /boot |
775 |
mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img |
776 |
|
777 |
<comment># Create a OpenBoot / SPARC64 TFTP image</comment> |
778 |
emerge sparc-utils |
779 |
cd /boot |
780 |
elftoaout kernel... -o kernel.aout |
781 |
piggyback64 kernel.aout System.map-... initrd-... |
782 |
mv kernel.aout openboot.img <comment># This is the boot image</comment> |
783 |
|
784 |
<comment># PXE does not need any more steps, the kernel and initrd can be used as is</comment> |
785 |
</pre> |
786 |
|
787 |
<p> |
788 |
Finally, copy this kernel to your TFTP server. The details are |
789 |
architecture-dependent and are beyond the scope of this guide. Please refer to |
790 |
the documentation for your platform. |
791 |
</p> |
792 |
|
793 |
</body> |
794 |
</section> |
795 |
|
796 |
<section> |
797 |
<title>NFS Setup</title> |
798 |
<body> |
799 |
|
800 |
<p> |
801 |
To setup a NFS share that contains the Installation CD, use the loop device to |
802 |
mount the ISO image and then copy the contents of the CD into the NFS share. As |
803 |
a nice extra, genkernel's initrd scripts will extract all tar.gz files located |
804 |
in the <path>/nfs/livecd/add/</path> directory. All you have to do here is copy |
805 |
the <c>modules-X.Y.Z.tar.gz</c> archive to the <path>/nfs/livecd/add/</path> |
806 |
directory. |
807 |
</p> |
808 |
|
809 |
<pre caption="Preparing the NFS share"> |
810 |
<comment># This assumes that /nfs/livecd is a exported NFS share</comment> |
811 |
mount /mnt/cdrom /tmp/gentoo-livecd.iso -o loop |
812 |
cp -p /mnt/cdrom /nfs/livecd |
813 |
umount /mnt/cdrom |
814 |
|
815 |
<comment># Copy the modules.tar.gz into /add</comment> |
816 |
mkdir /nfs/livecd/add |
817 |
cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add |
818 |
</pre> |
819 |
|
820 |
</body> |
821 |
</section> |
822 |
|
823 |
<section> |
824 |
<title>DHCP Setup</title> |
825 |
<body> |
826 |
|
827 |
<p> |
828 |
The netboot images will ask your DHCP server for an IP as well as a |
829 |
root-path parameter. Both can be specified per host using a MAC |
830 |
address to identify machines: |
831 |
</p> |
832 |
|
833 |
<pre caption="Sample client dhcpd.conf setup"> |
834 |
... |
835 |
|
836 |
host netbootableMachine { |
837 |
hardware ethernet 11:22:33:44:55:66; |
838 |
fixed-address 192.168.1.10; |
839 |
option root-path "192.168.1.2:/nfs/livecd"; |
840 |
} |
841 |
<comment># Here, 192.168.1.2 is the NFS server |
842 |
# While 192.168.1.10 will be the IP address of the netbooted machine</comment> |
843 |
... |
844 |
</pre> |
845 |
|
846 |
</body> |
847 |
</section> |
848 |
|
849 |
<section> |
850 |
<title>Netbooting Instructions</title> |
851 |
<body> |
852 |
|
853 |
<p> |
854 |
Netbooting itself is again very platform-specific. The important part |
855 |
is to specify the <c>ip=dhcp</c> and <c>init=/linuxrc</c> parameters |
856 |
on the kernel command line, as this will bring up the |
857 |
network interface and tell the initrd scripts to mount the Installation CD via |
858 |
NFS. Here are some platform-specific tips: |
859 |
</p> |
860 |
|
861 |
<pre caption="Netbooting Instructions"> |
862 |
<comment># Etherboot - insert the etherboot disk into the drive and reboot |
863 |
# The kernel command line was specified when the image was constructed</comment> |
864 |
|
865 |
<comment># Sparc64 - Hit Stop-A at the boot prompt </comment> |
866 |
ok boot net ip=dhcp init=/linuxrc |
867 |
|
868 |
<comment># PXE - Setup pxelinux (part of syslinux), then create a pxelinux.cfg/default along the lines of:</comment> |
869 |
|
870 |
DEFAULT gentoo |
871 |
TIMEOUT 40 |
872 |
PROMPT 1 |
873 |
|
874 |
LABEL gentoo |
875 |
KERNEL kernel-X.Y.Z |
876 |
APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp |
877 |
</pre> |
878 |
|
879 |
</body> |
880 |
</section> |
881 |
|
882 |
</chapter> |
883 |
|
884 |
<chapter> |
885 |
<title>Conclusion</title> |
886 |
|
887 |
<section> |
888 |
<title>To Automate or not to Automate?</title> |
889 |
<body> |
890 |
|
891 |
<p> |
892 |
The purpose of genkernel is to provide an (easier) alternative to the |
893 |
time-tested approach to kernel compilation. As always, you are free to decide |
894 |
on whether or not you want to automate the kernel compilation process. |
895 |
</p> |
896 |
|
897 |
</body> |
898 |
</section> |
899 |
|
900 |
</chapter> |
901 |
|
902 |
</guide> |