/[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.31 - (show annotations) (download) (as text)
Mon Jun 23 05:07:13 2008 UTC (6 years ago) by nightmorph
Branch: MAIN
Changes since 1.30: +27 -36 lines
File MIME type: application/xml
updated the splash options

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

  ViewVC Help
Powered by ViewVC 1.1.20