Bump version to 3.4.51
[proj/genkernel.git] / doc / genkernel.8.txt
1 GENKERNEL(8)
2 ============
3 :man source:   genkernel {genkernelversion}
4 :man manual:   genkernel {genkernelversion}
5
6
7 NAME
8 ----
9 genkernel - the Gentoo Linux automatic kernel compiler.
10
11
12 SYNOPSIS
13 --------
14 *genkernel* [options...] action
15
16
17 INTRODUCTION
18 ------------
19 Genkernel is designed to allow users who are not previously used to
20 compiling a kernel to use a similar setup to that one that is used on
21 the Gentoo LiveCDs which auto-detects your hardware.
22
23 Some users may also be interested in using genkernel for hardware which
24 requires initialization and a working kernel before it can be booted
25 because genkernel also automatically compiles your kernel modules,
26 allowing hardware which needs to be loaded with module parameters to be
27 used.
28
29
30 USAGE
31 -----
32 All that is needed to run genkernel is just `genkernel` with an
33 action and any flags you might need:
34
35 ------------------------------------------
36 # genkernel --menuconfig --no-clean --no-install all
37 ------------------------------------------
38
39 This would produce a kernel, asking you what how to configure it to
40 your desire, leaving alone any existing compiled object files, but not
41 installing anything.
42
43
44 ACTIONS
45 -------
46 An action tells genkernel what you want it to do  -  the following
47 actions are supported:
48
49 *all*::
50     Build all steps - the kernel, modules, and the ramdisk.
51 *bzImage*::
52     Build only the kernel.
53 *initramfs*::
54     Build only the ramdisk/initramfs.
55 *kernel*::
56     Build only the kernel and the modules.
57 *ramdisk*::
58     Build only the ramdisk/initramfs.
59
60
61 OPTIONS
62 -------
63 Genkernel supports the following options which alter its behaviour.
64 Certain options have *--no-* variants which do the opposite thing.
65 You can specify your options in any order.
66
67
68 CONFIGURATION OPTIONS
69 ~~~~~~~~~~~~~~~~~~~~~
70 *--config*=<file>::
71     Genkernel configuration file to use
72
73
74 DEBUGGING OPTIONS
75 ~~~~~~~~~~~~~~~~~
76 *--loglevel*=<0-5>::
77     This controls the out verbosity level of genkernel output - if
78     this is set to 0, minimal debugging is done; if this is set to 5
79     as much output as possible is given.
80
81 *--logfile*=<outfile>::
82     This outputs debugging data to the file <outfile>. By default
83     this is '/var/log/genkernel.log'.
84
85 *--*[*no-*]*color*::
86     Turns on, or off, output in color using escape sequences.
87
88 *--*[*no-*]*debug-cleanup*::
89     Turns on or off the full post-run cleanup for debug purposes.
90
91
92 KERNEL CONFIGURATION
93 ~~~~~~~~~~~~~~~~~~~~
94 *--*[*no-*]*menuconfig*::
95     Runs, or does not run "make menuconfig" after running "make oldconfig".
96
97 *--*[*no-*]*save-config*::
98     Saves, or does not save the kernel configuration to '/etc/kernels'
99     if the kernel is successfully compiled.
100
101 *--virtio*::
102     Adds Virtio support to kernel configuration.
103
104 *--*[*no-*]*gconfig*::
105     Runs, or does not run "make gconfig" after "make oldconfig".
106
107 *--*[*no-*]*xconfig*::
108     Runs, or does not run "make xconfig" after "make oldconfig".
109
110
111 KERNEL COMPILATION
112 ~~~~~~~~~~~~~~~~~~
113 *--*[*no-*]*clean*::
114     Runs, or does not run, "make clean" before compilation  -  this
115     erases any compiled object files in the kernel source tree but
116     does not have an impact on the kernel configuration.  Specifying
117     *--no-clean* implies *--no-mrproper*.
118
119 *--*[*no-*]*mrproper*::
120     Runs, or does not run, "make mrproper" before compilation - this
121     erases both any compiled object files in the kernel source tree
122     as well as the kernel configuration.
123
124 *--*[*no-*]*install*::
125     Installs,  or does not install the kernel to '/boot' after building.
126     The default is  *--install*.   If MOUNTBOOT is set in
127     '/etc/genkernel.conf'  then '/boot' will be automatically mounted if
128     it is not already mounted before the ramdisk and kernel images
129     are copied over.
130
131 *--*[*no-*]*symlink*::
132     Manages,  or does not manage, symlinks in '/boot' like the manual
133     kernel "make install" process does. A kernel (or,  depending on
134     options,  kernelz)  symlink will link to the most recently built
135     kernel image and a kernel.old (or kernelz.old) symlink will link
136     to the second most recently built image, if one exists.  Similar
137     symlinks (both * and *.old) are managed for initramfs and System.map.
138     The corresponding work products (i.e., the actual kernel
139     and initramfs images, and System.map) are also managed accordingly.
140     NOTE: Specifying   *--symlink*  does nothing unless
141     *--install* is also specified.
142
143 *--oldconfig*::
144     Implies *--no-clean*, and thus *--no-mrproper*, running a "make oldconfig".
145
146 *--*[*no-*]*splash*::
147     Installs, or not, framebuffer splash support into initramfs.
148
149 *--*[*no-*]*ramdisk-modules*::
150     Copies or does not copy configured modules to the ramdisk.
151
152 *--*[*no-*]*all-ramdisk-modules*::
153     Copies or does not copy all kernel modules to the initrd.
154
155 *--callback*=<...>::
156     Run the specified arguments in the current environment after the
157     kernel and modules have been compiled.
158
159 *--*[*no-*]*static*::
160         Builds, or does not build a monolithic kernel without any modules on any
161         initial ramdisks.
162
163
164 KERNEL LOCATIONS
165 ~~~~~~~~~~~~~~~~
166 *--kerneldir*=<dir>::
167     This specifies the location of the kernel sources;  the default
168     is '/usr/src/linux'.
169
170 *--kernel-config*=<file>::
171     This specifies a kernel configuration file to use for compilation;
172     by default genkernel uses the config from the previous
173     build of the same kernel version or a default kernel config if
174     there isn't a previous config.
175
176 *--module-prefix*=<dir>::
177     Prefix to kernel module destination, modules will be installed in
178     '<prefix>/lib/modules'.
179
180
181 LOW-LEVEL COMPILATION OPTIONS
182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183 *--kernel-cc*=<compiler>::
184     Compiler to use for the kernel compilation (e.g. distcc).
185
186 *--kernel-as*=<assembler>::
187     Assembler to use for the kernel compilation.
188
189 *--kernel-ld*=<linker>::
190     Linker to use for the kernel compilation.
191
192 *--kernel-cross-compile*=<cross var>::
193     CROSS_COMPILE kernel variable.
194
195 *--kernel-make*=<makeprg>::
196     GNU Make to use for the kernel compilation.
197
198 *--kernel-target*=<t>::
199     Override default make target (bzImage), note that values
200     like *--kernel-target=* are also valid (useful for Xen
201     based kernel sources)
202
203 *--kernel-binary*=<path>::
204     Override default kernel binary path (arch/foo/boot/bar)
205
206 *--utils-cc*=<compiler>::
207     Compiler to use for utilities.
208
209 *--utils-as*=<assembler>::
210     Assembler to use for utilities.
211
212 *--utils-ld*=<linker>::
213     Linker to use for utilities.
214
215 *--utils-make*=<makeprog>::
216     GNU Make to use for utilities.
217
218 *--utils-cross-compile*=<cross var>::
219     CROSS_COMPILE utils variable.
220
221 *--utils-arch*=<arch>::
222     Force to arch for utils only instead of autodetect.
223
224 *--*[*no-*]*mountboot*::
225     Mount, or not, BOOTDIR automatically if mountable.
226
227 *--bootdir*=<dir>::
228     Set the location of the boot-directory, default is '/boot'.
229
230 *--modprobedir*=<dir>::
231     Set the location of the modprobe.d-directory, default is '/etc/modprobe.d'.
232
233 *--makeopts*=<makeopts>::
234     GNU Make options such as -j2, etc.
235
236
237 INITIALIZATION
238 ~~~~~~~~~~~~~~
239 *--splash*=<theme>::
240     Enable framebuffer splash using <theme>.
241
242 *--splash-res*=<resolutions>::
243     Select gensplash resolutions to include.
244
245 *--*[*no-*]*splash*=<theme>::
246     If the extra argument is specified,  splash is forced using
247     <theme>  rather than the default theme specified in your splash
248     configuration. If *--no-splash* is specified, then splash is disabled.
249
250 *--do-keymap-auto*::
251     Force keymap selection at boot.
252
253 *--*[*no-*]*keymap*::
254     Enables or disables keymap selection at boot.
255
256 *--*[*no-*]*lvm*::
257         Adds or skips in LVM support from static binaries if they exist on the
258         system,  or compile static LVM binaries if static ones do not exist.
259
260 *--*[*no-*]*mdadm*::
261     Includes or excludes mdadm/mdmon support.
262     Without sys-fs/mdadm[static] installed, this will compile mdadm for you.
263
264 *--mdadm-config*=<file>::
265     Use <file> as configfile for MDADM.
266     By default the ramdisk will be built *without* an mdadm.conf and
267     will auto-detect arrays during boot-up.
268
269 *--*[*no-*]*dmraid*::
270     Includes or excludes DMRAID support.
271
272 *--*[*no-*]*e2fsprogs*::
273     Includes or excludes e2fsprogs.
274
275 *--*[*no-*]*zfs*::
276     Includes or excludes ZFS support.
277
278 *--*[*no-*]*multipath*::
279     Includes or excludes Multipath support
280
281 *--*[*no-*]*iscsi*::
282     Includes or excludes iSCSI support
283
284 *--bootloader*=*grub*::
285     Add new kernel to GRUB configuration.
286
287 *--linuxrc*=<file>::
288     Use <file> for the linuxrc instead of the genkernel linuxrc.
289
290 *--busybox-config*=<file>::
291     Specifies a user created busybox config.
292
293 *--genzimage*::
294         Make and install kernelz image from 'arch/powerpc/boot/zImage.initrd'.
295
296 *--*[*no-*]*disklabel*::
297     Includes or excludes disk label and uuid support in your initrd.
298
299 *--*[*no-*]*luks*::
300         Includes or excludes Luks support from static binaries if they exist on
301         the system.
302
303 *--*[*no-*]*gpg*::
304         Includes or excludes support for GnuPG 1.x, the portable standalone branch
305         of GnuPG. A key can be made from
306     `gpg --symmetric -o /path/to/LUKS-key.gpg /path/to/LUKS-key` .
307     After that, re-point the *root_key* argument to the new .gpg file.
308
309 *--*[*no-*]*busybox*::
310     Includes or excludes busybox in the initrd or initramfs.
311
312 *--*[*no-*]*unionfs*::
313     Includes or excludes support for unionfs
314
315 *--*[*no-*]*netboot*::
316     Creates or does not create a self-contained env in the initramfs
317
318 *--real-root*=<foo>::
319     Specify a default for *real_root*= kernel option.
320
321
322 INTERNALS
323 ~~~~~~~~~
324 *--arch-override*=<arch>::
325     Force the architecture settings described by the <arch>  profile
326     instead of autodetecting the running architecture.
327
328 *--cachedir*=<dir>::
329     Override the default cache location.
330
331 *--tempdir*=<dir>::
332     Sets genkernel's temporary working directory to <dir>.
333
334 *--*[*no-*]*postclear*::
335         Clears or skips clearing all tmp files and caches after genkernel has run.
336
337
338 OUTPUT SETTINGS
339 ~~~~~~~~~~~~~~~
340 *--kernname*=<...>::
341     Tag the kernel and initrd with a name, if not defined this
342     option defaults to genkernel
343
344 *--minkernpackage*=<tbz2>::
345     File to output a .tar.bz2'd kernel and initrd: no modules outside
346     of the initrd will be included...
347
348 *--modulespackage*=<tbz2>::
349     File to output a .tar.bz2'd modules after the callbacks have run
350
351 *--kerncache*=<tbz2>::
352     File to output a .tar.bz2'd kernel, contents of '/lib/modules/'
353     and the kernel config.  NOTE: This is created before the callbacks
354     are run.
355
356 *--*[*no-*]*kernel-sources*::
357     This option is only valid if kerncache is defined If there is a
358     valid kerncache no checks will be made against a kernel source
359     tree.
360
361 *--initramfs-overlay*=<dir>::
362     Directory structure to include in the initramfs, only available
363     on >=2.6 kernels
364
365 *--*[*no-*]*firmware*::
366     Enable or disables copying of firmware into initramfs.
367
368 *--firmware-dir*=<dir>::
369     Specify directory to copy firmware from (defaults to '/lib/firmware').
370
371 *--firmware-files*=<files>::
372     Specifies specific firmware files to copy. This overrides *--firmware-dir*.
373     For multiple files, separate the filenames with a comma.
374
375 *--*[*no-*]*integrated-initramfs*::
376         Builds or does not build the generated initramfs into the kernel instead
377         of keeping it as a separate file.
378
379 *--*[*no-*]*compress-initramfs*, *--*[*no-*]*compress-initrd*::
380         Compresses or does not compress the generated initramfs.
381
382 *--compress-initramfs-type*=<arg>::
383         Compression type for initramfs (best, xz, lzma, bzip2, gzip, lzop).
384         "Best" causes selection of the best available algorithm that is selected
385         in your kernel configuration.
386
387
388 RAMDISK/INITRAMFS OPTIONS
389 -------------------------
390 The following options can be passed as kernel parameters from the bootloader,
391 which the ramdisk & initramfs scripts would recognize.
392
393 *root*=<...>::
394     Specifies the device node of the root filesystem to mount.
395
396 *real_root*=<...>::
397     Legacy kernel parameter from kernel-2.4 initrd.
398     Does the same as *root*=, which should be used in its place.
399
400 *crypt_root*=<...>::
401     This specifies the device encrypted by Luks, which contains the
402     root filesystem to mount.
403
404 *crypt_swap*=<...>::
405     This specifies the swap device encrypted by Luks.
406
407 *root_key*=<...>::
408     In case your root is encrypted with a key, you can use a device
409     like a  usb pen to store the key.  This value should be the key
410     path relative to the mount point.
411
412 *root_keydev*=<...>::
413     If necessary provide the name of the device that carries the
414     root_key.   If unset while using root_key, it will automatically
415     look for the device in every boot.
416
417 *root_trim*=(yes|no)::
418     Enables TRIM support for a Luks-based root device.  Only useful
419     with SSD setups.  Have a look at 'http://en.wikipedia.org/wiki/TRIM'
420     for more information.
421
422 *swap_key*=<...>::
423     Same as root_key for swap.
424
425 *swap_keydev*=<...>::
426     Same as root_keydev for swap.
427
428 *crypt_silent*::
429     Set this to silent all the output related to the cryptographic
430     software,  and in case your encrypted device isn't open with the
431     key, it opens a shell in the initrd quietly.
432
433 *dodmraid*[=<...>]::
434     Activate Device-Mapper RAID and (optionally) pass arguments to it.
435
436 *init*=<...>::
437     Override location of init script, default is "/sbin/init".
438
439 *real_init*=<...>::
440     Legacy kernel parameter from kernel-2.4 initrd.
441     Does the same as *init*=, which should be used in its place.
442
443 *init_opts*=<...>::
444     Passes arguments to init on bootup.
445
446 *scandelay*[=<...>]::
447     Pauses for 10 seconds before running devfsd if no argument is
448     specified; otherwise pauses for the number of specified seconds.
449
450 *ip*=<...>::
451     Normally used to tell the kernel that it should start a network
452     interface. If present, the initrd will try to mount a  livecd
453     over NFS.
454
455 *nfsroot*=<...>::
456     If present,  the initrd will try to mount a livecd from that
457     location. Otherwise the location will be deduced from the DCHP
458     request (option root-path)
459
460 *dolvm*::
461     Activate LVM volumes on bootup
462
463 *lvmraid*=<...>::
464     Specify RAID devices to set up before the activation of LVM volumes.
465     Implies option *dolvm*.
466
467 *domdadm*::
468     Scan for RAID arrays on bootup
469
470 *dozfs*[=force]::
471     Scan for bootable ZFS pools on bootup. Optionally force import if
472     necessary.
473
474 *domultipath*::
475     Activate Multipath on bootup
476
477 *doscsi*::
478     Activate SCSI devices on bootup, necessary when SCSI support is
479     compiled as modules and you're using SCSI or SATA devices.
480
481 *keymap*='MAP'::
482     Set keymap to 'MAP', e.g. *keymap*=de.
483     For valid values of 'MAP' please see
484     '/usr/share/genkernel/defaults/keymaps/'.
485
486 *dokeymap*::
487     Use keymap.  Usage of *keymap*= implies this option, already.
488
489 *rootfstype*=<...>::
490     Specify the file system type to mount the real root filesystem as.
491     This can be useful when support for ext2/ext3/ext4 are
492     in competition.  Default is "auto".
493
494 *docache*::
495 *nocache*::
496     Enables/disables caching of CD contents in RAM.
497
498 *subdir*=<...>::
499     switch_root into "<CHROOT>/<SUBDIR>" instead of "<CHROOT>/".
500     <CHROOT> is "/newroot" (or "/union") usually.
501
502 *quiet*::
503     Do not print anything but error and warning messages during
504     the execution of the initramfs init scripts.
505
506 *debug*::
507     Drop into a debug shell early in the process.
508
509 *noload*=<...>::
510     List of modules to skip loading.
511     Separate using commas or spaces.
512
513 *nodetect*::
514     Skipping scanning modules using "modprobe <MODULE> -n".
515     Use *doload=* for specifying a whitelist of exceptions.
516
517 *doload*=<...>::
518     List of modules to load despite *nodetect*.
519
520 *domodules*::
521 *nomodules*::
522     Enables/disables loading of modules in general.
523
524 *CONSOLE*=<...>::
525 *console*=<...>::
526     Override location of console, default is "/dev/console".
527
528 *part*[=<0,1>]::
529 *partitionable*::
530         Enable/Disable partitionable RAIDs (metadata 0.x) during auto-run.
531         Standalone *part* and *partitionable* keywords for kernel compatability.
532
533 *iscsi_initiatorname*=<...>::
534 *iscsi_target*=<...>::
535 *iscsi_tgpt*=<...>::
536 *iscsi_address*=<...>::
537 *iscsi_port*=<...>::
538 *iscsi_username*=<...>::
539 *iscsi_password*=<...>::
540 *iscsi_username_in*=<...>::
541 *iscsi_password_in*=<...>::
542 *iscsi_debug*=<...>::
543 *iscsi_noibft*::
544     Specify iSCSI parameters.
545
546 *unionfs*::
547 *nounionfs*::
548     Enables/disables UnionFS.
549
550 *aufs*::
551     Enables support for AUFS2 (if available in the kernel).
552
553 *rootflags*=<...>::
554     Additional flags to mount the real root system with.
555     For example *rootflags*=noatime would make "-o ro,noatime".
556
557 *real_rootflags*=<...>::
558     Legacy kernel parameter from kernel-2.4 initrd.
559     Does the same as *rootflags*=, which should be used in its place.
560
561 *real_resume*=<...>::
562 *resume*=<...>::
563 *noresume*::
564     *noresume* disables any default resume parameters. *resume* and
565     *real_resume* specify a device via LABEL or UUID to use for for loading a
566     TuxOnICE, SWSUSP or Suspend2 resume image.
567
568 *cdroot*[=<...>]::
569 *cdroot_type*=<...>::
570 *cdroot_marker*=<...>::
571     Used for LiveCDs. *cdroot* without arguments will cause the initramfs to
572     scan all devices for a LiveCD. An argument to *cdroot* will cause it to
573     scan only that device. A LiveCD is any device containing a file with the
574     name & Path of *cdroot_marker* (default of "/livecd"). *cdroot_type*
575     (default of "auto") is the filesystem type to use while mounting devices
576     to check. On success, the LiveCD will be mounted at $CDROOT_PATH.
577
578 *loop*=<...>::
579 *looptype*=<...>::
580     Used for LiveCDs. After mounting the LiveCD or ISO, look for a file at
581     *loop*=path to use as a loopback image for the main type. Mount it with
582     filesystem type *looptype*. Possible values for *looptype*: normal,
583     squashfs, gcloop, zisofs, noloop, sgimips. If *looptype* is not specified,
584     a guess is made, based on the name or extension of *loop*.
585
586 *isoboot*=<...>::
587     Loop-mount an ISO file from the boot device to get the filesystem image.
588     Useful with chain-loading environments and USB keys.
589
590
591 NETBOOTING
592 ----------
593 The initrd scripts have limited support for network booting.   This is
594 activated if the *ip*=<...> kernel parameter was given. Please refer to
595 the genkernel guide at 'http://www.gentoo.org/doc/en/genkernel.xml' for
596 more information.
597
598 The initrd scripts will extract any *.tar.gz files found in the '/add'
599 directory of the livecd into the root filesystem during boot. This way
600 it is easy to extend a netbooted LiveCD i.e. add custom tools, or other
601 kernel modules.
602
603
604 REPORTING BUGS
605 --------------
606 If you believe you have found a bug in the genkernel scripts,  then
607 please file a bug on the Gentoo Linux Bugzilla against product
608 "Gentoo Hosted Projects" component "genkernel", i.e. at
609 'https://bugs.gentoo.org/enter_bug.cgi?product=Gentoo%20Hosted%20Projects&component=genkernel'.
610
611 If you're somewhat unsure if you hit a bug or not, file a bug an we'll find out together.
612 For general questions the is the gentoo-genkernel mailing list.  You can join the list
613 by sending empty mail to 'gentoo-genkernel+subscribe@lists.gentoo.org'.
614
615 We cannot assist you with
616 kernel compilation failures unless they are caused by a genkernel bug.
617
618 Kernel issues for Gentoo-supported kernels, including compilation failures
619 should go to 'https://bugs.gentoo.org/' and should be assigned to 'kernel@gentoo.org'.
620 Please check if an existing bug documents the same
621 issue before opening a new bug. Issues for kernel sources not supported
622 by Gentoo should go to their relevant authors.
623
624
625 AUTHORS
626 -------
627 - Tim Yamin <plasmaroo@gentoo.org>
628 - Eric Edgar <rocket@gentoo.org>
629 - Chris Gianelloni <wolf31o2@gentoo.org>
630 - Sebastian Pipping <sebastian@pipping.org>
631 - NFS Support by Thomas Seiler <thseiler@gmail.com>
632 - GnuPG 1.x integration by dacook <schism@subverted.org>
633 - MDADM integration by Matthias Dahl <ua_bugz_gentoo@mortal-soul.de>
634 - ZFS integration by Richard Yao <ryao@cs.stonybrook.edu>
635
636
637 SEE ALSO
638 --------
639 /etc/genkernel.conf - genkernel configuration file