/[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.35 - (hide annotations) (download) (as text)
Thu Jan 20 07:51:37 2011 UTC (3 years, 11 months ago) by nightmorph
Branch: MAIN
Changes since 1.34: +38 -30 lines
File MIME type: application/xml
bring genkernel.xml up-to-date with some changes from sping. also removed the 'obsolete' disclaimer.

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

  ViewVC Help
Powered by ViewVC 1.1.20