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