/[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.31 - (hide annotations) (download) (as text)
Mon Jun 23 05:07:13 2008 UTC (6 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.30: +27 -36 lines
File MIME type: application/xml
updated the splash options

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

  ViewVC Help
Powered by ViewVC 1.1.20