/[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.19 - (hide annotations) (download) (as text)
Thu Jul 28 12:40:47 2005 UTC (9 years, 1 month ago) by jkt
Branch: MAIN
Changes since 1.18: +2 -2 lines
File MIME type: application/xml
Fixing <date> stuff, *no content change*

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 jkt 1.19 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/genkernel.xml,v 1.18 2005/07/25 20:28:53 plasmaroo 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.18 <version>1.3</version>
30 jkt 1.19 <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 plasmaroo 1.18 <li>
248     <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
250     modules have been built, but before building the initrd image. This may
251     be useful if you want to install external modules in the initrd image by
252     emerging the relevant item(s) with the callback feature, and then
253     redefining a genkernel module group.
254     </li>
255 swift 1.1 </ul>
256    
257     <ul>
258 plasmaroo 1.17 <li>
259     <b>--<c>no-</c>install</b>: Activates <e>[or deactivates]</e> the
260     <c>make install</c> command, which installs your new kernel image,
261     configuration file, initrd image and system map onto your mounted boot
262     partition. Any compiled modules will be installed as well.
263     </li>
264     <li>
265     <b>--<c>no-</c>initrdmodules</b>: Refrains from copying any modules to
266     the genkernel-created initrd image. This flag is an exception to the rule
267     about the <c>no-</c> prefix; omission of this prefix creates an invalid
268     genkernel flag.
269     </li>
270     <li>
271     <b>--genzimage</b>: Creates the initrd image, prior to the kernel image.
272     (This hack currently applies only to PPC Pegasos systems.)
273     </li>
274 swift 1.1 </ul>
275    
276     </body>
277     </section>
278 plasmaroo 1.17
279 swift 1.1 <section>
280 plasmaroo 1.17 <title>Compiler Flags</title>
281 swift 1.1 <body>
282    
283     <p>
284 plasmaroo 1.17 The following flags are supported by genkernel, and are passed to the relevant
285     applications while the kernel is being assembled. These flags affect the
286     <e>compiler</e> used for the kernel compilation process, albeit at a much lower
287     level.
288 swift 1.1 </p>
289    
290     <ul>
291 plasmaroo 1.17 <li>
292     <b>--kernel-cc=<c>someCompiler</c></b>: Specifies the compiler employed
293     during the kernel compilation process.
294     </li>
295     <li>
296     <b>--kernel-ld=<c>someLinker</c></b>: Specifies the linker employed
297     during the kernel compilation process.
298     </li>
299     <li>
300     <b>--kernel-as=<c>someAssembler</c></b>: Specifies the assembler employed
301     during the kernel compilation process.
302     </li>
303     <li>
304     <b>--kernel-make=<c>someMake</c></b>: Specifies an alternative to the
305     <e>GNU make</e> utility employed during the kernel compilation process.
306     </li>
307     </ul>
308    
309     <ul>
310     <li>
311     <b>--utils-cc=<c>someCompiler</c></b>: Specifies the compiler employed
312     during the compilation of support utilities.
313     </li>
314     <li>
315     <b>--utils-ld=<c>someLinker</c></b>: Specifies the linker employed during
316     the compilation of support utilities.
317     </li>
318     <li>
319     <b>--utils-as=<c>someAssembler</c></b>: Specifies the assembler employed
320     during the compilation of support utilities.
321     </li>
322     <li>
323     <b>--utils-make=<c>someMake</c></b>: Specifies an alternative to the
324     <e>GNU make</e> utility employed during the compilation of support
325     utilities.
326     </li>
327     </ul>
328    
329     <ul>
330     <li>
331     <b>--makeopts=<c>-jX</c></b>: Specifies the number of concurrent threads
332     that the make utility can implement while the kernel (and utilities) are
333     being compiled. The variable <b>'X'</b> is a number obtained by adding
334     one (1) to the number of CPUs used by the system. So, for a system with
335     one CPU, the appropriate flag is <c>-j2</c>; a system with two CPUs will
336     use the <c>-j3</c> flag, and so on. <e>(A system with one processor that
337     supports Hyper-Threading&#8482; (HT) Technology can use the</e><c>-j3</c>
338     <e>flag, provided Symmetric Multi-Processing (SMP) support is enabled in
339     the kernel.)</e>
340     </li>
341 swift 1.1 </ul>
342    
343 plasmaroo 1.17 </body>
344     </section>
345    
346     <section>
347     <title>Debugging Flags</title>
348     <body>
349    
350     <p>
351     The use 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 swift 1.1 <ul>
356 plasmaroo 1.17 <li>
357     <b>--debuglevel=<c>verblevel</c></b>: Controls the level of
358     verbosity for information provided by genkernel. The variable
359     <c>verblevel</c> is an integer between 0 and 5. The level '0' represents
360     minimal output, while '5' provides as much information as possible about
361     genkernel's activities during the kernel compilation process.
362     </li>
363     <li>
364     <b>--debugfile=<path>/path/to/outputfile</path></b>: Ignores the value
365     set by the <c>--debuglevel</c> argument, and sends <b>all</b> debugging
366     data produced by genkernel to the specified output file, which is located
367     at <path>/var/log/genkernel.log</path> by default.
368     </li>
369     <li>
370     <b>--no-color</b>: Activates [or deactivates] colored output of debugging
371     information (reported by genkernel) using escape sequences.
372     </li>
373 swift 1.1 </ul>
374    
375 plasmaroo 1.17 </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 swift 1.1 <ul>
389 plasmaroo 1.18 <li>
390     <b>--<c>no-</c>bootsplash</b>: Activates <e>[or deactivates]</e> support
391     for <uri link="http://www.bootsplash.org/">bootsplash</uri> in the
392     genkernel-built initrd image. The bootsplash feature is supported on a
393     limited number of architectures, and a kernel that supports bootsplash
394     is also required.
395     </li>
396     <li>
397     <b>--<c>no-</c>gensplash</b>: Activates <e>[or deactivates]</e> support
398     for <uri link="http://dev.gentoo.org/~spock/projects/gensplash/">gensplash</uri>
399     support in the genkernel-built initrd image. The gensplash utility is
400     intended to be a replacement for bootsplash, and is designed for use with
401     2.6.x series kernels. To override the default theme used by gensplash,
402     use <b>--gensplash=<c>PreferredTheme</c></b> (where <c>PreferredTheme</c>
403     is the title of one of the directories inside the
404     <path>/etc/splash/</path> directory.
405     </li>
406     <li>
407     <b>--gensplash-res=<c>PreferredResolution</c></b>: This flag allows you
408     to select which splash screen resolutions will be supported in the initrd
409     during the start-up of the system. This is useful for two reasons: First,
410     you are able to select only the splash screen resolution(s) relevant to
411     your system. Second, you avoid the unnecessary increase in the disk space
412     required by initrd (since the initrd does not have to support resolutions
413     that are irrelevant for your system configuration.) However, you may want
414     to omit this flag if the kernel is being compiled for an Installation CD;
415     this allows gensplash support for all possible resolutions.
416     </li>
417     <li>
418     <b>--do-keymap-auto</b>: Force keymap selection during the boot
419     sequence.
420     </li>
421     <li>
422     <b>--lvm2</b>: Includes support for storage using via <uri
423     link="http://sources.redhat.com/lvm2/">Logical Volume Management</uri>
424     (LVM2) from <e>static</e> binaries, if available to the system. Relevant
425     (static) LVM2 binaries are compiled if they are unavailable. Be sure to
426     install the lvm2 package on your system with <c>emerge lvm2</c> before
427     enabling this flag, and review the <uri
428 plasmaroo 1.17 link="http://www.gentoo.org/doc/en/lvm2.xml">Gentoo LVM2
429     Installation</uri> guide.
430     </li>
431     <li>
432 plasmaroo 1.18 <b>--evms2</b>: Includes support for storage using the <uri
433     link="http://evms.sourceforge.net/">Enterprise Volume Management
434     System</uri> (EVMS2), if available. Be sure to install the evms package
435     on your system with <c>USE=static emerge evms2</c> before using this
436     (genkernel) flag. <e>(Omitting the </e><c>USE=static</c> <e>flag during
437     package installation will fail to include the necessary static binaries.)
438     </e>
439 plasmaroo 1.17 </li>
440     <li>
441 plasmaroo 1.18 <b>--dmraid</b>: Includes support for <uri
442     link="http://people.redhat.com/~heinzm/sw/dmraid/readme">DMRAID</uri>;
443     the utility which creates RAID mappings using the kernel device-mapper
444     subsystem. DMRAID discovers, activates, deactivates and displays
445     properties of software RAID sets (ATARAID, for example) and contained
446     DOS partitions.
447 plasmaroo 1.17 </li>
448     <li>
449     <b>--linuxrc=/path/to/your/linuxrc</b>: Specifies a user-created
450     <e>linuxrc</e> &#8212; a script that is initialized during the start-up
451     stage of the kernel, prior to the actual boot process. (A default linuxrc
452     script should be in the <path>/usr/share/genkernel/</path> directory.)
453     This script allows you to boot into a small, modularized kernel and load
454     the drivers that are needed (as modules) by the system.
455     </li>
456     <li>
457     <b>--cachedir=/path/to/alt/dir/</b>: Overrides the default cache location
458     used while compiling the kernel.
459     </li>
460     <li>
461     <b>--tempdir=/path/to/new/tempdir/</b>: Specifies the location of the
462     temporary directory used by genkernel while compiling the kernel.
463     </li>
464 plasmaroo 1.18 <li>
465     <b>--unionfs</b>: Includes support for the <uri
466     link="http://www.fsl.cs.sunysb.edu/project-unionfs.html">Unification File
467     System</uri> in the initrd image.
468     </li>
469 swift 1.1 </ul>
470    
471     </body>
472     </section>
473 plasmaroo 1.17
474 swift 1.1 <section>
475 plasmaroo 1.17 <title>Miscellaneous Flags</title>
476 swift 1.1 <body>
477    
478     <p>
479 plasmaroo 1.17 The assortment of flags listed below are supported by genkernel, but do not fit
480     neatly into any of the other categories:
481 swift 1.1 </p>
482    
483     <ul>
484 plasmaroo 1.17 <li>
485     <b>--mountboot</b>: Detects whether or not the <path>/boot/</path>
486     directory needs to be mounted on a separate partition. It will check
487     <path>/etc/fstab</path> script for instructions on how to mount the boot
488     partition on a file system (if needed).
489     </li>
490     <li>
491 plasmaroo 1.18 <b>--kernname=<c>NickName</c></b>: Allows you to modify the name of the
492     kernel and initrd images in the <path>/boot/</path> directory, so that
493     the images produced are kernel-<c>NickName</c>-version and
494     initramfs-<c>NickName</c>-version.
495 plasmaroo 1.17 </li>
496 swift 1.1 </ul>
497    
498     </body>
499     </section>
500 plasmaroo 1.17
501    
502 swift 1.1 <section>
503 plasmaroo 1.17 <title>Possible Actions</title>
504 swift 1.1 <body>
505    
506     <p>
507 plasmaroo 1.17 An action tells genkernel what to build. Currently, the following actions are
508     supported:
509 swift 1.1 </p>
510    
511 plasmaroo 1.17 <ul>
512     <li><c>initrd</c>: Only builds the initrd image</li>
513 plasmaroo 1.18 <li><c>bzImage</c>: Only builds the kernel image</li>
514 plasmaroo 1.17 <li><c>kernel</c>: Only builds the kernel image and modules</li>
515     <li><c>all</c>: Builds all stages &#8212; the initrd, kernel image and
516     modules.</li>
517     </ul>
518 swift 1.1
519     <p>
520 plasmaroo 1.17 The last action, <c>all</c>, is recommended for most users since it builds the
521     stages required for a functional kernel. Remember, an <e>action</e> simply
522     tells genkernel what to <e>build</e>, not <e>install</e>.
523 swift 1.1 </p>
524    
525     </body>
526     </section>
527 plasmaroo 1.17
528    
529 swift 1.1 <section>
530 plasmaroo 1.17 <title>Bootloader Configuration</title>
531 swift 1.1 <body>
532    
533     <p>
534 plasmaroo 1.17 To set up genkernel to work with your bootloader, three or four changes should
535     to the bootloader's configuration file:
536 swift 1.1 </p>
537    
538     <ol>
539 plasmaroo 1.17 <li>
540     Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the kernel
541     parameters passed to the kernel image.
542     </li>
543     <li>
544     Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
545     passed to the kernel image, if <path>/dev/hda3</path> contains your root
546     partition.
547     </li>
548     <li>
549     If you are using bootsplash, add a suitable mode line such as
550     <c>vga=0x317</c> to the parameters passed to the kernel and also add
551     <c>splash=verbose</c> or <c>splash=silent</c> depending on the
552     verboseness you require from your bootloader.
553     </li>
554     <li>
555     Add the initrd information as required by the bootloader. Consult the
556     <uri link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=10">
557     Bootloader Configuration Chapter</uri> of the Gentoo Handbook for details
558     on how to make your bootloader initrd-aware.
559 swift 1.1 </li>
560     </ol>
561    
562     </body>
563     </section>
564 plasmaroo 1.17
565     </chapter>
566    
567     <chapter>
568     <title>Configuration Options</title>
569    
570 swift 1.9 <section>
571 plasmaroo 1.17 <title>Editing /etc/genkernel.conf</title>
572 swift 1.9 <body>
573    
574     <p>
575 plasmaroo 1.17 Passing flags to genkernel from the command line can be cumbersome, especially
576     if you have about a dozen flags:
577     </p>
578    
579     <pre caption="Running genkernel (overloaded with flags)">
580     # genkernel --debuglevel=5 --no-color --no-mrproper --clean --gensplash\
581     --kerneldir=/path/to/alternate/kernel/sources --install --menuconfig --udev\
582     --kernel-config=/path/to/preferred/configfile --save-config --mountboot all
583     </pre>
584    
585     <p>Fortunately, there is a configuration file where most of the basic options
586     can be set (or changed) as necessary. What follows is a rundown of the more
587     relevant options:
588     </p>
589    
590     <ul>
591     <li>
592     <b>MENUCONFIG=<c>[yes|no]</c></b>: This option is equivalent to the
593     <c>--menuconfig</c> flag used by genkernel, which in turn uses the
594     <c>make menuconfig</c> command to invoke a command-line based kernel
595     configuration utility. To invoke the utility automatically during kernel
596     configuration via this script, set this option to 'yes' here; otherwise,
597     choose 'no'.
598     </li>
599     <li>
600     <b>CLEAN=<c>[yes|no]</c></b>: Setting this option to 'yes' is equivalent
601     to the <c>--clean</c> flag used by genkernel, and invokes the
602     <c>make clean</c> command to remove all object files and dependencies
603     from the kernel's source tree. Setting this option to 'no' creates a
604     cascade effect &#8212; it is equivalent to genkernel's <c>--no-clean</c>
605     flag, which disables the <c>make clean</c> command and implies
606     genkernel's <c>--no-mrproper</c> flag &#8212; essentially nullifying the
607     <c>make mrproper</c> command.
608     </li>
609     <li>
610     <b>MRPROPER=<c>[yes|no]</c></b>: Setting this option to 'yes' is
611     equivalent to <c>--mrproper</c> flag used by genkernel, and invokes the
612     <c>make mrproper</c> command, which purges the kernel source tree of any
613     configuration files. Selecting 'no' here is equivalent to genkernel's
614     <c>--no-mrproper</c> flag, which disables the <c>make mrproper</c>
615     command.
616     </li>
617     <li>
618     <b>MOUNTBOOT=<c>[yes|no]</c></b>: Setting this option to 'yes' is
619     equivalent to the <c>--mountboot</c> flag, and automatically mounts the
620     <path>/boot/</path> directory (if needed) at compile time. If the
621     <path>/boot/</path> directory is on a separate partition, consider
622     enabling this option; it will make for one less (essential) step to
623     remember later.
624     </li>
625     <li>
626     <b>SAVE_CONFIG=<c>[yes|no]</c></b>: After configuring the kernel, the
627     selected options are stored as <path>.config</path> in the kernel source
628     tree. This script may be overwritten during the next kernel compilation,
629     or even purged from the kernel source tree. Choosing 'yes' here is
630     equivalent to the <c>--save-config</c> flag, and stores all options
631     selected during kernel configuration as a script in the
632     <path>/etc/kernels/</path> directory. Choosing 'no' preserves the
633     <e>status quo</e>.
634     </li>
635     <li>
636     <b>USECOLOR=<c>[yes|no]</c></b>: Setting this option to 'yes' is
637     equivalent to the <c>--color</c> flag, which colors genkernel's output
638     to ease debugging (when needed.)
639     </li>
640     <li>
641     <b>DEBUGLEVEL=<c>[0|1|2|3|4|5]</c></b>: This option is for adjusting the
642     verbosity of the output produced by genkernel &#8212; setting this option
643     to '0' with <c>--debuglevel=0</c> will suppress all output produced by
644     genkernel; setting this option to '5' with <c>--debuglevel=5</c>
645     provides the user with all output produced by genkernel.
646     </li>
647     </ul>
648    
649     <p>
650     By choosing the appropriate options in <path>/etc/genkernel.conf</path>, you
651     can halve the number of flags passed to genkernel from the command line:
652     </p>
653    
654     <pre caption="Running genkernel (with flags), after employing genkernel.conf">
655     # genkernel --gensplash --kerneldir=/path/to/alternate/kernel/sources --udev\
656     --kernel-config=/path/to/preferred/configfile --install all
657     </pre>
658    
659     <p>
660     Identical results are obtained from both approaches, but the latter has most of
661     the options stored in a script that can be modified at a later date.
662 swift 1.9 </p>
663    
664     </body>
665     </section>
666 plasmaroo 1.17
667 swift 1.1 </chapter>
668    
669     <chapter>
670 plasmaroo 1.17 <title>Network-Booting with genkernel</title>
671    
672 swift 1.1 <section>
673 plasmaroo 1.17 <title>Network Booting from an Installation CD</title>
674     <body>
675    
676     <p>
677     The genkernel utility can build kernel and initrd images that provide support
678     for network booting, or <e>netboot</e>ing . With any luck, you should be able
679     to netboot any recent computer into the environment provided by the
680     Installation CD.
681     </p>
682    
683     <p>
684     The magic lies in genkernel's linuxrc script: it will try to <e>netmount</e>
685     the Installation CD using NFS. From there, <e>the init scripts</e> of the
686     Installation CD can take over, as if the CD was present locally.
687     </p>
688    
689     </body>
690     </section>
691    
692     <section>
693     <title>Building Kernel and Initrd Images with Support for Netbooting</title>
694 swift 1.1 <body>
695    
696     <p>
697 plasmaroo 1.17 To enable support for netbooting, include the following options while
698     configuring the kernel:
699 swift 1.1 </p>
700    
701 plasmaroo 1.17 <warn>
702     Support for netbooting with genkernel is experimental and may contain bugs.
703     </warn>
704    
705     <p>
706     First, the kernel image must include the drivers for your Network Interface
707 plasmaroo 1.18 Cards (NIC). Normally, drivers for such devices will be compiled as modules.
708     However, it is essential (for netbooting) that you such drivers compiled
709     directly into the kernel image and <b>not</b> as modules.
710 plasmaroo 1.17 </p>
711    
712     <pre caption="Configuring a 2.6.x series kernel to support your NIC driver">
713     Device Drivers --->
714     Networking Support --->
715     Ethernet (10 or 100Mbit) --->
716     [*] Ethernet (10 or 100Mbit)
717     &lt;*&gt; the driver for your network card
718     <comment>(Be sure to select &lt;*&gt; and not &lt;m&gt;)</comment>
719     </pre>
720    
721     <p>
722     Secondly, we suggest that you enable <c>IP: kernel level
723     autoconfiguration</c> and the <c>IP: DHCP support</c> options. This avoids an
724     unnecessary layer of complexity since the IP address and the NFS path to the
725     Installation CD can be configured on a DHCP server. Of course, this means the
726     kernel command line will remain constant for any machine &#8212; which is very
727     important for <e>etherbooting</e>.
728     </p>
729    
730     <pre caption="Configuring a 2.6.x series kernel to support DHCP">
731     Device Drivers --->
732     Networking Support --->
733     Networking options
734     [*] TCP/IP networking--->
735     [*] IP: kernel level autoconfiguration
736     [*] IP: DHCP support
737     <comment>(These options tell the kernel to send a DHCP request at bootup.)</comment>
738     </pre>
739    
740     <p>
741     Additionally, you should enable SquashFS because most modern Gentoo
742     Installation CDs require it. Support for SquashFS is not included with the
743     generic kernel source tree. To enable SquashFS, apply the necessary patches to
744     the generic kernel source or install <c>gentoo-sources</c>.
745     </p>
746    
747     <pre caption="Configuring the kernel to support SquashFS">
748     File systems--->
749     Miscellaneous filesystems --->
750     [*] SquashFS 2.X - Squashed file system support
751     </pre>
752    
753     <p>
754     Once the compilation process is completed, create a compressed <e>tarball</e>
755     (tar.gz) that contains the kernel's modules. This step is only necessary if
756     your kernel version does not match the kernel image version on the Installation
757     CD.
758     </p>
759    
760     <pre caption="Creating a compressed tarball containing the kernel modules">
761     <comment># Create a tar.gz containing all the modules</comment>
762     cd /
763     tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/
764     </pre>
765    
766     <p>
767     Depending on your network boot mechanism, you will need to do some of the
768     following steps:
769     </p>
770    
771     <pre caption="Creating a boot image">
772     <comment># Create a etherboot image</comment>
773     emerge mknbi
774     cd /boot
775     mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img
776    
777     <comment># Create a OpenBoot / SPARC64 TFTP image</comment>
778     emerge sparc-utils
779     cd /boot
780     elftoaout kernel... -o kernel.aout
781     piggyback64 kernel.aout System.map-... initrd-...
782     mv kernel.aout openboot.img <comment># This is the boot image</comment>
783    
784     <comment># PXE does not need any more steps, the kernel and initrd can be used as is</comment>
785     </pre>
786    
787     <p>
788     Finally, copy this kernel to your TFTP server. The details are
789     architecture-dependent and are beyond the scope of this guide. Please refer to
790     the documentation for your platform.
791     </p>
792    
793     </body>
794     </section>
795    
796     <section>
797     <title>NFS Setup</title>
798     <body>
799    
800 swift 1.1 <p>
801 plasmaroo 1.17 To setup a NFS share that contains the Installation CD, use the loop device to
802     mount the ISO image and then copy the contents of the CD into the NFS share. As
803     a nice extra, genkernel's initrd scripts will extract all tar.gz files located
804     in the <path>/nfs/livecd/add/</path> directory. All you have to do here is copy
805     the <c>modules-X.Y.Z.tar.gz</c> archive to the <path>/nfs/livecd/add/</path>
806     directory.
807 swift 1.1 </p>
808    
809 plasmaroo 1.17 <pre caption="Preparing the NFS share">
810     <comment># This assumes that /nfs/livecd is a exported NFS share</comment>
811     mount /mnt/cdrom /tmp/gentoo-livecd.iso -o loop
812     cp -p /mnt/cdrom /nfs/livecd
813     umount /mnt/cdrom
814    
815     <comment># Copy the modules.tar.gz into /add</comment>
816     mkdir /nfs/livecd/add
817     cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add
818     </pre>
819    
820 swift 1.1 </body>
821     </section>
822 plasmaroo 1.17
823 swift 1.1 <section>
824 plasmaroo 1.17 <title>DHCP Setup</title>
825 swift 1.1 <body>
826    
827 plasmaroo 1.17 <p>
828     The netboot images will ask your DHCP server for an IP as well as a
829     root-path parameter. Both can be specified per host using a MAC
830     address to identify machines:
831     </p>
832    
833     <pre caption="Sample client dhcpd.conf setup">
834     ...
835    
836     host netbootableMachine {
837     hardware ethernet 11:22:33:44:55:66;
838     fixed-address 192.168.1.10;
839     option root-path "192.168.1.2:/nfs/livecd";
840     }
841     <comment># Here, 192.168.1.2 is the NFS server
842     # While 192.168.1.10 will be the IP address of the netbooted machine</comment>
843     ...
844     </pre>
845 swift 1.1
846     </body>
847     </section>
848 plasmaroo 1.17
849 swift 1.1 <section>
850 plasmaroo 1.17 <title>Netbooting Instructions</title>
851 swift 1.1 <body>
852    
853 plasmaroo 1.17 <p>
854     Netbooting itself is again very platform-specific. The important part
855     is to specify the <c>ip=dhcp</c> and <c>init=/linuxrc</c> parameters
856     on the kernel command line, as this will bring up the
857     network interface and tell the initrd scripts to mount the Installation CD via
858     NFS. Here are some platform-specific tips:
859     </p>
860    
861     <pre caption="Netbooting Instructions">
862     <comment># Etherboot - insert the etherboot disk into the drive and reboot
863     # The kernel command line was specified when the image was constructed</comment>
864    
865     <comment># Sparc64 - Hit Stop-A at the boot prompt </comment>
866     ok boot net ip=dhcp init=/linuxrc
867    
868     <comment># PXE - Setup pxelinux (part of syslinux), then create a pxelinux.cfg/default along the lines of:</comment>
869    
870     DEFAULT gentoo
871     TIMEOUT 40
872     PROMPT 1
873    
874     LABEL gentoo
875     KERNEL kernel-X.Y.Z
876     APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp
877     </pre>
878    
879     </body>
880     </section>
881    
882     </chapter>
883    
884     <chapter>
885     <title>Conclusion</title>
886    
887     <section>
888     <title>To Automate or not to Automate?</title>
889     <body>
890 swift 1.1
891 plasmaroo 1.17 <p>
892     The purpose of genkernel is to provide an (easier) alternative to the
893 plasmaroo 1.18 time-tested approach to kernel compilation. As always, you are free to decide
894     on whether or not you want to automate the kernel compilation process.
895 plasmaroo 1.17 </p>
896 swift 1.1
897     </body>
898     </section>
899 plasmaroo 1.17
900 swift 1.1 </chapter>
901 plasmaroo 1.17
902 swift 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20