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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.33 - (show annotations) (download) (as text)
Tue Dec 7 12:24:29 2010 UTC (3 years, 4 months ago) by nightmorph
Branch: MAIN
Changes since 1.32: +8 -7 lines
File MIME type: application/xml
typo fix, via ML

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

  ViewVC Help
Powered by ViewVC 1.1.20