/[gentoo]/xml/htdocs/doc/en/genkernel.xml
Gentoo

Contents of /xml/htdocs/doc/en/genkernel.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.24 - (show annotations) (download) (as text)
Sun Sep 4 23:04:25 2005 UTC (9 years, 3 months ago) by cam
Branch: MAIN
Changes since 1.23: +13 -15 lines
File MIME type: application/xml
Some minor english-only corrections.

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/genkernel.xml,v 1.23 2005/08/18 11:33:54 neysx 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.1</version>
30 <date>2005-08-11</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.0/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 [or does not save] 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</e><c>-j3</c>
332 <e>flag, provided Symmetric Multi-Processing (SMP) support is enabled in
333 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 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 [or deactivates] colored output of debugging
364 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 binaries.)
430 </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 stage of
442 the kernel, prior to the actual boot process. (A default linuxrc script
443 should be in the <path>/usr/share/genkernel/</path> directory.) This script
444 allows you to boot into a small, modularized kernel and load the drivers
445 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><c>all</c>: Builds all stages — the initrd, kernel image and modules.</li>
504 </ul>
505
506 <p>
507 The last action, <c>all</c>, is recommended for most users since it builds the
508 stages required for a functional kernel. Remember, an <e>action</e> simply
509 tells genkernel what to <e>build</e>, not <e>install</e>.
510 </p>
511
512 </body>
513 </section>
514 <section>
515 <title>Bootloader Configuration</title>
516 <body>
517
518 <p>
519 To set up genkernel to work with your bootloader, three or four changes should
520 be applied to the bootloader's configuration file:
521 </p>
522
523 <ol>
524 <li>
525 Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the kernel parameters
526 passed to the kernel image.
527 </li>
528 <li>
529 Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
530 passed to the kernel image, if <path>/dev/hda3</path> contains your root
531 partition.
532 </li>
533 <li>
534 If you are using bootsplash, add a suitable mode line such as
535 <c>vga=0x317</c> to the parameters passed to the kernel and also add
536 <c>splash=verbose</c> or <c>splash=silent</c> depending on the verboseness
537 you require from your bootloader.
538 </li>
539 <li>
540 Add the initrd information as required by the bootloader. Consult the <uri
541 link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">Bootloader
542 Configuration Chapter</uri> of the Gentoo Handbook for details on how to
543 make your bootloader initrd-aware.
544 </li>
545 </ol>
546
547 </body>
548 </section>
549 </chapter>
550
551 <chapter>
552 <title>Configuration Options</title>
553 <section>
554 <title>Editing /etc/genkernel.conf</title>
555 <body>
556
557 <p>
558 Passing flags to genkernel from the command line can be cumbersome, especially
559 if you have about a dozen flags:
560 </p>
561
562 <pre caption="Running genkernel (overloaded with flags)">
563 # <i>genkernel --debuglevel=5 --no-color --no-mrproper --clean --gensplash \
564 --kerneldir=/path/to/alternate/kernel/sources --install --menuconfig \
565 --kernel-config=/path/to/preferred/configfile --save-config --mountboot all</i>
566 </pre>
567
568 <p>
569 Fortunately, there is a configuration file where most of the basic options can
570 be set (or changed) as necessary. What follows is a rundown of the more
571 relevant options:
572 </p>
573
574 <ul>
575 <li>
576 <b>MENUCONFIG=<c>[yes|no]</c></b>: This option is equivalent to the
577 <c>--menuconfig</c> flag used by genkernel, which in turn uses the <c>make
578 menuconfig</c> command to invoke a command-line based kernel configuration
579 utility. To invoke the utility automatically during kernel configuration
580 via this script, set this option to 'yes' here; otherwise, choose 'no'.
581 </li>
582 <li>
583 <b>CLEAN=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent to
584 the <c>--clean</c> flag used by genkernel, and invokes the <c>make
585 clean</c> command to remove all object files and dependencies from the
586 kernel's source tree. Setting this option to 'no' creates a cascade effect
587 &#8212; it is equivalent to genkernel's <c>--no-clean</c> flag, which
588 disables the <c>make clean</c> command and implies genkernel's
589 <c>--no-mrproper</c> flag &#8212; essentially nullifying the <c>make
590 mrproper</c> command.
591 </li>
592 <li>
593 <b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent
594 to <c>--mrproper</c> flag used by genkernel, and invokes the <c>make
595 mrproper</c> command, which purges the kernel source tree of any
596 configuration files. Selecting 'no' here is equivalent to genkernel's
597 <c>--no-mrproper</c> flag, which disables the <c>make mrproper</c> command.
598 </li>
599 <li>
600 <b>MOUNTBOOT=<c>[yes|no]</c></b>: Setting this option to 'yes' is
601 equivalent to the <c>--mountboot</c> flag, and automatically mounts the
602 <path>/boot/</path> directory (if needed) at compile time. If the
603 <path>/boot/</path> directory is on a separate partition, consider enabling
604 this option; it will make for one less (essential) step to remember later.
605 </li>
606 <li>
607 <b>SAVE_CONFIG=<c>[yes|no]</c></b>: After configuring the kernel, the
608 selected options are stored as <path>.config</path> in the kernel source
609 tree. This script may be overwritten during the next kernel compilation, or
610 even purged from the kernel source tree. Choosing 'yes' here is equivalent
611 to the <c>--save-config</c> flag, and stores all options selected during
612 kernel configuration as a script in the <path>/etc/kernels/</path>
613 directory. Choosing 'no' preserves the <e>status quo</e>.
614 </li>
615 <li>
616 <b>USECOLOR=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent
617 to the <c>--color</c> flag, which colors genkernel's output to ease
618 debugging (when needed.)
619 </li>
620 <li>
621 <b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the
622 verbosity of the output produced by genkernel — setting this option to '0'
623 with <c>--debuglevel=0</c> will suppress all output produced by genkernel;
624 setting this option to '5' with <c>--debuglevel=5</c> provides the user
625 with all output produced by genkernel.
626 </li>
627 </ul>
628
629 <p>
630 By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you
631 can halve the number of flags passed to genkernel from the command line:
632 </p>
633
634 <pre caption="Running genkernel (with flags), after employing genkernel.conf">
635 # <i>genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources \
636 --kernel-config=/path/to/preferred/configfile --install all</i>
637 </pre>
638
639 <p>
640 Identical results are obtained from both approaches, but the latter has most of
641 the options stored in a script that can be modified at a later date.
642 </p>
643
644 </body>
645 </section>
646 </chapter>
647
648 <chapter>
649 <title>Network-Booting with genkernel</title>
650 <section>
651 <title>Network Booting from an Installation CD</title>
652 <body>
653
654 <p>
655 The genkernel utility can build kernel and initrd images that provide support
656 for network booting, or <e>netboot</e>ing. With any luck, you should be able
657 to netboot any recent computer into the environment provided by the
658 Installation CD.
659 </p>
660
661 <p>
662 The magic lies in genkernel's linuxrc script: it will try to <e>netmount</e>
663 the Installation CD using NFS. From there, <e>the init scripts</e> of the
664 Installation CD can take over, as if the CD was present locally.
665 </p>
666
667 </body>
668 </section>
669 <section>
670 <title>Building Kernel and Initrd Images with Support for Netbooting</title>
671 <body>
672
673 <p>
674 To enable support for netbooting, include the following options while
675 configuring the kernel:
676 </p>
677
678 <warn>
679 Support for netbooting with genkernel is experimental and may contain bugs.
680 </warn>
681
682 <p>
683 First, the kernel image must include the drivers for your Network Interface
684 Cards (NIC). Normally, drivers for such devices will be compiled as modules.
685 However, it is essential (for netbooting) that you have such drivers compiled
686 directly into the kernel image and <b>not</b> as modules.
687 </p>
688
689 <pre caption="Configuring a 2.6.x series kernel to support your NIC driver">
690 Device Drivers --->
691 Networking Support --->
692 Ethernet (10 or 100Mbit) --->
693 [*] Ethernet (10 or 100Mbit)
694 &lt;*&gt; the driver for your network card
695 <comment>(Be sure to select &lt;*&gt; and not &lt;M&gt;)</comment>
696 </pre>
697
698 <p>
699 Secondly, we suggest that you enable <c>IP: kernel level autoconfiguration</c>
700 and the <c>IP: DHCP support</c> options. This avoids an unnecessary layer of
701 complexity since the IP address and the NFS path to the Installation CD can be
702 configured on a DHCP server. Of course, this means the kernel command line
703 will remain constant for any machine — which is very important for
704 <e>etherbooting</e>.
705 </p>
706
707 <pre caption="Configuring a 2.6.x series kernel to support DHCP">
708 Device Drivers --->
709 Networking Support --->
710 Networking options
711 [*] TCP/IP networking--->
712 [*] IP: kernel level autoconfiguration
713 [*] IP: DHCP support
714 <comment>(These options tell the kernel to send a DHCP request at bootup.)</comment>
715 </pre>
716
717 <p>
718 Additionally, you should enable SquashFS because most modern Gentoo
719 Installation CDs require it. Support for SquashFS is not included with the
720 generic kernel source tree. To enable SquashFS, apply the necessary patches to
721 the generic kernel source or install <c>gentoo-sources</c>.
722 </p>
723
724 <pre caption="Configuring the kernel to support SquashFS">
725 File systems--->
726 Miscellaneous filesystems --->
727 [*] SquashFS 2.X - Squashed file system support
728 </pre>
729
730 <p>
731 Once the compilation process is completed, create a compressed <e>tarball</e>
732 (tar.gz) that contains the kernel's modules. This step is only necessary if
733 your kernel version does not match the kernel image version on the Installation
734 CD.
735 </p>
736
737 <pre caption="Creating a compressed tarball containing the kernel modules">
738 <comment>(Create a tar.gz containing all the modules)</comment>
739 # <i>cd /</i>
740 # <i> tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/</i>
741 </pre>
742
743 <p>
744 Depending on your network boot mechanism, you will need to do some of the
745 following steps:
746 </p>
747
748 <pre caption="Creating a boot image">
749 <comment>(Create an etherboot image)</comment>
750 # <i>emerge mknbi</i>
751 # <i>cd /boot</i>
752 # <i>mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img</i>
753
754 <comment>(Create a OpenBoot / SPARC64 TFTP image)</comment>
755 # <i>emerge sparc-utils</i>
756 # <i>cd /boot</i>
757 # <i>elftoaout kernel... -o kernel.aout</i>
758 # <i>piggyback64 kernel.aout System.map-... initrd-...</i>
759 # <i>mv kernel.aout openboot.img</i> <comment>(This is the boot image)</comment>
760
761 <comment>(PXE does not need any more steps, the kernel and initrd can be used as is)</comment>
762 </pre>
763
764 <p>
765 Finally, copy this kernel to your TFTP server. The details are
766 architecture-dependent and are beyond the scope of this guide. Please refer to
767 the documentation for your platform.
768 </p>
769
770 </body>
771 </section>
772 <section>
773 <title>NFS Setup</title>
774 <body>
775
776 <p>
777 To setup a NFS share that contains the Installation CD, use the loop device to
778 mount the ISO image and then copy the contents of the CD into the NFS share. As
779 a nice extra, genkernel's initrd scripts will extract all tar.gz files located
780 in the <path>/nfs/livecd/add/</path> directory. All you have to do here is copy
781 the <c>modules-X.Y.Z.tar.gz</c> archive to the <path>/nfs/livecd/add/</path>
782 directory.
783 </p>
784
785 <pre caption="Preparing the NFS share">
786 <comment>(This assumes that /nfs/livecd is a exported NFS share)</comment>
787 # <i>mount /mnt/cdrom /tmp/gentoo-livecd.iso -o loop</i>
788 # <i>cp -p /mnt/cdrom /nfs/livecd</i>
789 # <i>umount /mnt/cdrom</i>
790
791 <comment>(Copy the modules.tar.gz into /add)</comment>
792 # <i>mkdir /nfs/livecd/add</i>
793 # <i>cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add</i>
794 </pre>
795
796 </body>
797 </section>
798 <section>
799 <title>DHCP Setup</title>
800 <body>
801
802 <p>
803 The netboot images will ask your DHCP server for an IP as well as a root-path
804 parameter. Both can be specified per host using a MAC address to identify
805 machines:
806 </p>
807
808 <pre caption="Sample client dhcpd.conf setup">
809 ...
810
811 host netbootableMachine {
812 hardware ethernet 11:22:33:44:55:66;
813 fixed-address 192.168.1.10;
814 option root-path "192.168.1.2:/nfs/livecd";
815 }
816 <comment># Here, 192.168.1.2 is the NFS server
817 # While 192.168.1.10 will be the IP address of the netbooted machine</comment>
818 ...
819 </pre>
820
821 </body>
822 </section>
823 <section>
824 <title>Netbooting Instructions</title>
825 <body>
826
827 <p>
828 Netbooting itself is again very platform-specific. The important part is to
829 specify the <c>ip=dhcp</c> and <c>init=/linuxrc</c> parameters on the kernel
830 command line, as this will bring up the network interface and tell the initrd
831 scripts to mount the Installation CD via NFS. Here are some platform-specific
832 tips:
833 </p>
834
835 <pre caption="Netbooting Instructions">
836 <comment># Etherboot - insert the etherboot disk into the drive and reboot
837 # The kernel command line was specified when the image was constructed</comment>
838
839 <comment># Sparc64 - Hit Stop-A at the boot prompt</comment>
840 ok boot net ip=dhcp init=/linuxrc
841
842 <comment># PXE - Setup pxelinux (part of syslinux),
843 then create a pxelinux.cfg/default along the lines of:</comment>
844
845 DEFAULT gentoo
846 TIMEOUT 40
847 PROMPT 1
848
849 LABEL gentoo
850 KERNEL kernel-X.Y.Z
851 APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp
852 </pre>
853
854 </body>
855 </section>
856 </chapter>
857
858 <chapter>
859 <title>Conclusion</title>
860 <section>
861 <title>To Automate or not to Automate?</title>
862 <body>
863
864 <p>
865 The purpose of genkernel is to provide an (easier) alternative to the
866 time-tested approach to kernel compilation. As always, you are free to decide
867 on whether or not you want to automate the kernel compilation process.
868 </p>
869
870 </body>
871 </section>
872 </chapter>
873
874 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20