GENKERNEL(8)
============
:man source:   genkernel {genkernelversion}
:man manual:   genkernel {genkernelversion}


NAME
----
genkernel - the Gentoo Linux automatic kernel compiler.


SYNOPSIS
--------
*genkernel* [options...] action


INTRODUCTION
------------
Genkernel is designed to allow users who are not previously used to
compiling a kernel to use a similar setup to that one that is used on
the Gentoo LiveCDs which auto-detects your hardware.

Some users may also be interested in using genkernel for hardware which
requires initialization and a working kernel before it can be booted
because genkernel also automatically compiles your kernel modules,
allowing hardware which needs to be loaded with module parameters to be
used.


USAGE
-----
All that is needed to run genkernel is just `genkernel` with an
action and any flags you might need:

------------------------------------------
# genkernel --menuconfig --no-clean --no-install all
------------------------------------------

This would produce a kernel, asking you what how to configure it to
your desire, leaving alone any existing compiled object files, but not
installing anything.


ACTIONS
-------
An action tells genkernel what you want it to do  -  the following
actions are supported:

*all*::
    Build all steps - the kernel, modules, and the ramdisk.
*bzImage*::
    Build only the kernel.
*initramfs*::
    Build only the ramdisk/initramfs.
*kernel*::
    Build only the kernel and the modules.
*ramdisk*::
    Build only the ramdisk/initramfs.


OPTIONS
-------
Genkernel supports the following options which alter its behaviour.
Certain options have *--no-* variants which do the opposite thing.
You can specify your options in any order.


CONFIGURATION OPTIONS
~~~~~~~~~~~~~~~~~~~~~
*--config*=<file>::
    Genkernel configuration file to use


DEBUGGING OPTIONS
~~~~~~~~~~~~~~~~~
*--loglevel*=<0-5>::
    This controls the out verbosity level of genkernel output - if
    this is set to 0, minimal debugging is done; if this is set to 5
    as much output as possible is given.

*--logfile*=<outfile>::
    This outputs debugging data to the file <outfile>. By default
    this is '/var/log/genkernel.log'.

*--*[*no-*]*color*::
    Turns on, or off, output in color using escape sequences.


KERNEL CONFIGURATION
~~~~~~~~~~~~~~~~~~~~
*--*[*no-*]*menuconfig*::
    Runs, or does not run "make menuconfig" after running "make oldconfig".

*--*[*no-*]*nconfig*::
    Runs, or does not run "make nconfig" after running "make oldconfig".

*--*[*no-*]*save-config*::
    Saves, or does not save the kernel configuration to '/etc/kernels'
    if the kernel is successfully compiled.

*--*[*no-*]*gconfig*::
    Runs, or does not run "make gconfig" after "make oldconfig".

*--*[*no-*]*xconfig*::
    Runs, or does not run "make xconfig" after "make oldconfig".


KERNEL COMPILATION
~~~~~~~~~~~~~~~~~~
*--*[*no-*]*clean*::
    Runs, or does not run, "make clean" before compilation  -  this
    erases any compiled object files in the kernel source tree but
    does not have an impact on the kernel configuration.  Specifying
    *--no-clean* implies *--no-mrproper*.

*--*[*no-*]*mrproper*::
    Runs, or does not run, "make mrproper" before compilation - this
    erases both any compiled object files in the kernel source tree
    as well as the kernel configuration.

*--*[*no-*]*install*::
    Installs,  or does not install the kernel to '/boot' after building.
    The default is  *--install*.   If MOUNTBOOT is set in
    '/etc/genkernel.conf'  then '/boot' will be automatically mounted if
    it is not already mounted before the ramdisk and kernel images
    are copied over.

*--*[*no-*]*symlink*::
    Manages,  or does not manage, symlinks in '/boot' like the manual
    kernel "make install" process does. A kernel (or,  depending on
    options,  kernelz)  symlink will link to the most recently built
    kernel image and a kernel.old (or kernelz.old) symlink will link
    to the second most recently built image, if one exists.  Similar
    symlinks (both * and *.old) are managed for initramfs and System.map.
    The corresponding work products (i.e., the actual kernel
    and initramfs images, and System.map) are also managed accordingly.
    NOTE: Specifying   *--symlink*  does nothing unless
    *--install* is also specified.

*--oldconfig*::
    Implies *--no-clean*, and thus *--no-mrproper*, running a "make oldconfig".

*--*[*no-*]*splash*::
    Installs, or not, framebuffer splash support into initramfs.

*--*[*no-*]*ramdisk-modules*::
    Copies or does not copy configured modules to the ramdisk.

*--*[*no-*]*all-ramdisk-modules*::
    Copies or does not copy all kernel modules to the initrd.

*--callback*=<...>::
    Run the specified arguments in the current environment after the
    kernel and modules have been compiled.

*--*[*no-*]*static*::
    Builds, or does not build a monolithic kernel without any modules on any
    initial ramdisks.


KERNEL LOCATIONS
~~~~~~~~~~~~~~~~
*--kerneldir*=<dir>::
    This specifies the location of the kernel sources;  the default
    is '/usr/src/linux'.

*--kernel-config*=<file>::
    This specifies a kernel configuration file to use for compilation;
    by default genkernel uses the config from the previous
    build of the same kernel version or a default kernel config if
    there isn't a previous config.

*--module-prefix*=<dir>::
    Prefix to kernel module destination, modules will be installed in
    '<prefix>/lib/modules'.


LOW-LEVEL COMPILATION OPTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*--kernel-cc*=<compiler>::
    Compiler to use for the kernel compilation (e.g. distcc).

*--kernel-as*=<assembler>::
    Assembler to use for the kernel compilation.

*--kernel-ld*=<linker>::
    Linker to use for the kernel compilation.

*--kernel-make*=<makeprg>::
    GNU Make to use for the kernel compilation.

*--kernel-target*=<t>::
    Override default make target (bzImage), note that values
    like *--kernel-target=* are also valid (useful for Xen
    based kernel sources)

*--kernel-binary*=<path>::
    Override default kernel binary path (arch/foo/boot/bar)

*--utils-cc*=<compiler>::
    Compiler to use for utilities.

*--utils-as*=<assembler>::
    Assembler to use for utilities.

*--utils-ld*=<linker>::
    Linker to use for utilities.

*--utils-make*=<makeprog>::
    GNU Make to use for utilities.

*--utils-arch*=<arch>::
    Force to arch for utils only instead of autodetect.

*--*[*no-*]*mountboot*::
    Mount, or not, BOOTDIR automatically if mountable.

*--bootdir*=<dir>::
    Set the location of the boot-directory, default is '/boot'.

*--modprobedir*=<dir>::
    Set the location of the modprobe.d-directory, default is '/etc/modprobe.d'.

*--makeopts*=<makeopts>::
    GNU Make options such as -j2, etc.


INITIALIZATION
~~~~~~~~~~~~~~
*--splash*=<theme>::
    Enable framebuffer splash using <theme>.

*--splash-res*=<resolutions>::
    Select gensplash resolutions to include.

*--*[*no-*]*splash*=<theme>::
    If the extra argument is specified,  splash is forced using
    <theme>  rather than the default theme specified in your splash
    configuration. If *--no-splash* is specified, then splash is disabled.

*--*[*no-*]*plymouth*::
    Installs, or not, plymouth into the initramfs. If "splash" will be
    passed at boot, plymouth will be activated.

*--plymouth-theme*=<theme>::
    Embeds the given plymouth theme into the initramfs.

*--do-keymap-auto*::
    Force keymap selection at boot.

*--*[*no-*]*keymap*::
    Enables or disables keymap selection at boot.

*--*[*no-*]*udev*::
        Adds or exclude in udev support from static binaries if they exist on
        the system.

*--*[*no-*]*lvm*::
    Adds or skips in LVM support from static binaries if they exist on the
    system,  or compile static LVM binaries if static ones do not exist.

*--*[*no-*]*mdadm*::
    Includes or excludes mdadm/mdmon support.
    Without sys-fs/mdadm[static] installed, this will compile mdadm for you.

*--mdadm-config*=<file>::
    Use <file> as configfile for MDADM.
    By default the ramdisk will be built *without* an mdadm.conf and
    will auto-detect arrays during boot-up.

*--*[*no-*]*dmraid*::
    Includes or excludes DMRAID support.

*--*[*no-*]*e2fsprogs*::
    Includes or excludes e2fsprogs.

*--*[*no-*]*btrfs*::
    Includes or excludes btrfs RAID support.

*--*[*no-*]*zfs*::
    Includes or excludes ZFS support.

*--*[*no-*]*multipath*::
    Includes or excludes Multipath support

*--*[*no-*]*iscsi*::
    Includes or excludes iSCSI support

*--bootloader*=*grub*::
    Add new kernel to GRUB configuration.

*--linuxrc*=<file>::
    Use <file> for the linuxrc instead of the genkernel linuxrc.

*--busybox-config*=<file>::
    Specifies a user created busybox config.

*--genzimage*::
    Make and install kernelz image from 'arch/powerpc/boot/zImage.initrd'.

*--*[*no-*]*luks*::
    Includes or excludes Luks support from static binaries if they exist on
    the system.

*--*[*no-*]*gpg*::
    Includes or excludes support for GnuPG 1.x, the portable standalone branch
    of GnuPG. A key can be made from
    `gpg --symmetric -o /path/to/LUKS-key.gpg /path/to/LUKS-key` .
    After that, re-point the *root_key* argument to the new .gpg file.

*--*[*no-*]*busybox*::
    Includes or excludes busybox in the initrd or initramfs.

*--*[*no-*]*netboot*::
    Creates or does not create a self-contained env in the initramfs

*--real-root*=<foo>::
    Specify a default for *real_root*= kernel option.


INTERNALS
~~~~~~~~~
*--arch-override*=<arch>::
    Force the architecture settings described by the <arch>  profile
    instead of autodetecting the running architecture.

*--cachedir*=<dir>::
    Override the default cache location.

*--tempdir*=<dir>::
    Sets genkernel's temporary working directory to <dir>.

*--*[*no-*]*postclear*::
    Clears or skips clearing all tmp files and caches after genkernel has run.


OUTPUT SETTINGS
~~~~~~~~~~~~~~~
*--kernname*=<...>::
    Tag the kernel and initrd with a name, if not defined this
    option defaults to genkernel

*--appendname*=<...>::
    Append a text to the kernel and initrd's name, if not defined this
    option defaults to empty

*--minkernpackage*=<tbz2>::
    File to output a .tar.bz2'd kernel and initrd: no modules outside
    of the initrd will be included...

*--modulespackage*=<tbz2>::
    File to output a .tar.bz2'd modules after the callbacks have run

*--kerncache*=<tbz2>::
    File to output a .tar.bz2'd kernel, contents of '/lib/modules/'
    and the kernel config.  NOTE: This is created before the callbacks
    are run.

*--*[*no-*]*kernel-sources*::
    This option is only valid if kerncache is defined If there is a
    valid kerncache no checks will be made against a kernel source
    tree.

*--initramfs-overlay*=<dir>::
    Directory structure to include in the initramfs, only available
    on >=2.6 kernels

*--*[*no-*]*firmware*::
    Enable or disables copying of firmware into initramfs.

*--firmware-dir*=<dir>::
    Specify directory to copy firmware from (defaults to '/lib/firmware').

*--firmware-files*=<files>::
    Specifies specific firmware files to copy. This overrides *--firmware-dir*.
    For multiple files, separate the filenames with a comma.

*--*[*no-*]*firmware-install*::
    Enable or disables installation of firmware onto root filesystem.
    Please note this is deprecated, and installing
    *sys-kernel/linux-firmware* should be preferred instead.

*--*[*no-*]*integrated-initramfs*::
    Builds or does not build the generated initramfs into the kernel instead
    of keeping it as a separate file.

*--*[*no-*]*compress-initramfs*, *--*[*no-*]*compress-initrd*::
    Compresses or does not compress the generated initramfs.

*--compress-initramfs-type*=<arg>::
    Compression type for initramfs (best, xz, lzma, bzip2, gzip, lzop, lz4).
    "Best" causes selection of the best available algorithm that is selected
    in your kernel configuration.


RAMDISK OPTIONS
---------------
The following options can be passed as kernel parameters from the bootloader,
which the ramdisk scripts would recognize.

*root*=<...>::
    Specifies the device node of the root filesystem to mount.

*real_root*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *root*=, which should be used in its place.

*crypt_root*=<...>::
    This specifies the device encrypted by Luks, which contains the
    root filesystem to mount. If you intend to use multiple devices
    cooperating in the building of a single root device node (like
    for instance in the case of dmcrypts -> software raid), please
    use crypt_roots= instead.

*crypt_roots*=<...>::
    This specifies the devices encrypted by Luks, which concur in
    the availability of a device node used for the root filesystem.
    For instance, you could have two separately encrypted partitions
    on separate disks that are part of a software raid setup. You just
    need to declare multiple crypt_roots= statements each one containing
    one device path. Please keep in mind that the entries will be processed
    in the order they are declared. If you use crypt_roots=, remember to
    remove any reference to crypt_root=. They all share the same root_key=
    and root_keydev=.

*crypt_swap*=<...>::
    This specifies the swap device encrypted by Luks. If you have more than
    one encrypted swap, please use crypt_swaps= instead.

*crypt_swaps*=<...>::
    This specifies the swap devices encrypted by Luks. You just
    need to declare multiple crypt_swaps= statements each one containing
    one device path. Please keep in mind that the entries will be processed
    in the order they are declared. If you use crypt_swaps=, remember to
    remove any reference to crypt_swap=. They all share the same root_key=
    and root_keydev=.

*root_key*=<...>::
    In case your root is encrypted with a key, you can use a device
    like a  usb pen to store the key.  This value should be the key
    path relative to the mount point.

*root_keydev*=<...>::
    If necessary provide the name of the device that carries the
    root_key.   If unset while using root_key, it will automatically
    look for the device in every boot.

*root_trim*=(yes|no)::
    Enables TRIM support for a Luks-based root device.  Only useful
    with SSD setups.  Have a look at 'http://en.wikipedia.org/wiki/TRIM'
    for more information.

*swap_key*=<...>::
    Same as root_key for swap.

*swap_keydev*=<...>::
    Same as root_keydev for swap.

*crypt_silent*::
    Set this to silent all the output related to the cryptographic
    software,  and in case your encrypted device isn't open with the
    key, it opens a shell in the initrd quietly.

*dodmraid*[=<...>]::
    Activate Device-Mapper RAID and (optionally) pass arguments to it.

*init*=<...>::
    Override location of init script, default is "/sbin/init".

*real_init*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *init*=, which should be used in its place.

*init_opts*=<...>::
    Passes arguments to init on bootup.

*scandelay*[=<...>]::
    Pauses for 10 seconds before running devfsd if no argument is
    specified; otherwise pauses for the number of specified seconds.

*ip*=<...>::
    Normally used to tell the kernel that it should start a network
    interface. If present, the initrd will try to mount a  livecd
    over NFS.

*nfsroot*=<...>::
    If present,  the initrd will try to mount a livecd from that
    location. Otherwise the location will be deduced from the DCHP
    request (option root-path)

*dolvm*::
    Activate LVM volumes on bootup

*lvmraid*=<...>::
    Specify RAID devices to set up before the activation of LVM volumes.
    Implies option *dolvm*.

*domdadm*::
    Scan for RAID arrays on bootup

*dozfs*[=force]::
    Scan for bootable ZFS pools on bootup. Optionally force import if
    necessary.

*domultipath*::
    Activate Multipath on bootup

*doscsi*::
    Activate SCSI devices on bootup, necessary when SCSI support is
    compiled as modules and you're using SCSI or SATA devices.

*keymap*='MAP'::
    Set keymap to 'MAP', e.g. *keymap*=de.
    For valid values of 'MAP' please see
    '/usr/share/genkernel/defaults/keymaps/'.

*dokeymap*::
    Use keymap.  Usage of *keymap*= implies this option, already.

*rootfstype*=<...>::
    Specify the file system type to mount the real root filesystem as.
    This can be useful when support for ext2/ext3/ext4 are
    in competition.  Default is "auto".

*docache*::
*nocache*::
    Enables/disables caching of CD contents in RAM.

*subdir*=<...>::
    switch_root into "<CHROOT>/<SUBDIR>" instead of "<CHROOT>/".
    <CHROOT> is "/newroot" (or "/union") usually.

*quiet*::
    Do not print anything but error and warning messages during
    the execution of the initramfs init scripts.

*debug*::
    Drop into a debug shell early in the process.

*noload*=<...>::
    List of modules to skip loading.
    Separate using commas or spaces.

*nodetect*::
    Skipping scanning modules using "modprobe <MODULE> -n".
    Use *doload=* for specifying a whitelist of exceptions.

*doload*=<...>::
    List of modules to load despite *nodetect*.

*domodules*::
*nomodules*::
    Enables/disables loading of modules in general.

*CONSOLE*=<...>::
*console*=<...>::
    Override location of console, default is "/dev/console".

*part*[=<0,1>]::
*partitionable*::
    Enable/Disable partitionable RAIDs (metadata 0.x) during auto-run.
    Standalone *part* and *partitionable* keywords for kernel compatability.

*iscsi_initiatorname*=<...>::
*iscsi_target*=<...>::
*iscsi_tgpt*=<...>::
*iscsi_address*=<...>::
*iscsi_port*=<...>::
*iscsi_username*=<...>::
*iscsi_password*=<...>::
*iscsi_username_in*=<...>::
*iscsi_password_in*=<...>::
*iscsi_debug*=<...>::
*iscsi_noibft*::
    Specify iSCSI parameters.

*aufs*::
    Enables support for AUFS2 (if available in the kernel).

*overlayfs*::
    Enables support for Overlay FS (if available in the kernel).

*rootflags*=<...>::
    Additional flags to mount the real root system with.
    For example *rootflags*=noatime would make "-o ro,noatime".

*real_rootflags*=<...>::
    Legacy kernel parameter from kernel-2.4 initrd.
    Does the same as *rootflags*=, which should be used in its place.

*real_resume*=<...>::
*resume*=<...>::
*noresume*::
    *noresume* disables any default resume parameters. *resume* and
    *real_resume* specify a device via LABEL or UUID to use for loading a
    SWSUSP resume image.

*cdroot*[=<...>]::
*cdroot_type*=<...>::
*cdroot_marker*=<...>::
    Used for LiveCDs. *cdroot* without arguments will cause the initramfs to
    scan all devices for a LiveCD. An argument to *cdroot* will cause it to
    scan only that device. A LiveCD is any device containing a file with the
    name & Path of *cdroot_marker* (default of "/livecd"). *cdroot_type*
    (default of "auto") is the filesystem type to use while mounting devices
    to check. On success, the LiveCD will be mounted at $CDROOT_PATH.

*loop*=<...>::
*looptype*=<...>::
    Used for LiveCDs. After mounting the LiveCD or ISO, look for a file at
    *loop*=path to use as a loopback image for the main type. Mount it with
    filesystem type *looptype*. Possible values for *looptype*: normal,
    squashfs, gcloop, zisofs, noloop, sgimips. If *looptype* is not specified,
    a guess is made, based on the name or extension of *loop*.

*isoboot*=<...>::
    Loop-mount an ISO file from the boot device to get the filesystem image.
    Useful with chain-loading environments and USB keys.


HOOKS
-----
Genkernel provides a hook mechanism similar to the kernel's 'install.d' and
'postinst.d' features. To use a hook, create a folder with the hook name in
'/etc/kernels' and put any scripts you would like to execute inside. These
hooks are run in the order detailed below and the files in them are run in
alphanumeric order as described by the 'run-parts' documentation. 

*/postbuild.d*::
    Ran after the kernel is built.
*/postinstall.d*::
    Ran after the kernel is installed. 
*/postinitramfs.d*::
    Ran after the ramdisk/initramfs is built/installed.
*/postgen.d*::
    Ran after genekernel has completed it's tasks, but before cleanup.


NETBOOTING
----------
The initrd scripts have limited support for network booting.   This is
activated if the *ip*=<...> kernel parameter was given. Please refer to
the genkernel guide at 'http://www.gentoo.org/doc/en/genkernel.xml' for
more information.

The initrd scripts will extract any *.tar.gz files found in the '/add'
directory of the livecd into the root filesystem during boot. This way
it is easy to extend a netbooted LiveCD i.e. add custom tools, or other
kernel modules.


REPORTING BUGS
--------------
If you believe you have found a bug in the genkernel scripts,  then
please file a bug on the Gentoo Linux Bugzilla against product
"Gentoo Hosted Projects" component "genkernel", i.e. at
'https://bugs.gentoo.org/enter_bug.cgi?product=Gentoo%20Hosted%20Projects&component=genkernel'.

If you're somewhat unsure if you hit a bug or not, file a bug an we'll find out together.
For general questions the is the gentoo-genkernel mailing list.  You can join the list
by sending empty mail to 'gentoo-genkernel+subscribe@lists.gentoo.org'.

We cannot assist you with
kernel compilation failures unless they are caused by a genkernel bug.

Kernel issues for Gentoo-supported kernels, including compilation failures
should go to 'https://bugs.gentoo.org/' and should be assigned to 'kernel@gentoo.org'.
Please check if an existing bug documents the same
issue before opening a new bug. Issues for kernel sources not supported
by Gentoo should go to their relevant authors.


AUTHORS
-------
- Tim Yamin <plasmaroo@gentoo.org>
- Eric Edgar <rocket@gentoo.org>
- Chris Gianelloni <wolf31o2@gentoo.org>
- Sebastian Pipping <sebastian@pipping.org>
- NFS Support by Thomas Seiler <thseiler@gmail.com>
- GnuPG 1.x integration by dacook <schism@subverted.org>
- MDADM integration by Matthias Dahl <ua_bugz_gentoo@mortal-soul.de>
- ZFS integration by Richard Yao <ryao@cs.stonybrook.edu>


SEE ALSO
--------
/etc/genkernel.conf - genkernel configuration file
