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