/[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.17 - (hide annotations) (download) (as text)
Sun Jul 24 16:51:15 2005 UTC (9 years, 1 month ago) by plasmaroo
Branch: MAIN
Changes since 1.16: +712 -271 lines
File MIME type: application/xml
Update to 3.2.0 and restructure and reword (thanks to major contributions from Jimi Ayodele) and add netbooting information (thanks to contributions
from Thomas Seiler).

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

  ViewVC Help
Powered by ViewVC 1.1.20