/[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.33 - (hide annotations) (download) (as text)
Tue Dec 7 12:24:29 2010 UTC (3 years, 10 months ago) by nightmorph
Branch: MAIN
Changes since 1.32: +8 -7 lines
File MIME type: application/xml
typo fix, via ML

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

  ViewVC Help
Powered by ViewVC 1.1.20