/[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.41 - (show annotations) (download) (as text)
Mon Sep 30 18:01:26 2013 UTC (13 months, 3 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.40: +2 -2 lines
File MIME type: application/xml
Genkernel guide is now at https://wiki.gentoo.org/wiki/Genkernel

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

  ViewVC Help
Powered by ViewVC 1.1.20