/[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.25 - (hide annotations) (download) (as text)
Sun Sep 4 23:18:51 2005 UTC (8 years, 11 months ago) by cam
Branch: MAIN
Changes since 1.24: +28 -26 lines
File MIME type: application/xml
Fixed typo in mount arguments order + some "international" style corrections.

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

  ViewVC Help
Powered by ViewVC 1.1.20