/[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.41 - (hide annotations) (download) (as text)
Mon Sep 30 18:01:26 2013 UTC (11 months, 2 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.40: +2 -2 lines
File MIME type: application/xml
Genkernel guide is now at https://wiki.gentoo.org/wiki/Genkernel

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

  ViewVC Help
Powered by ViewVC 1.1.20