/[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.35 - (show annotations) (download) (as text)
Thu Jan 20 07:51:37 2011 UTC (3 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.34: +38 -30 lines
File MIME type: application/xml
bring genkernel.xml up-to-date with some changes from sping. also removed the 'obsolete' disclaimer.

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

  ViewVC Help
Powered by ViewVC 1.1.20