path: root/doc/genkernel.8.txt

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-*]*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-cross-compile*=<cross var>::
    CROSS_COMPILE kernel variable.

*--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-cross-compile*=<cross var>::
    CROSS_COMPILE utils variable.

*--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.

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

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

*--*[*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-*]*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-*]*disklabel*::
    Includes or excludes disk label and uuid support in your 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-*]*unionfs*::
    Includes or excludes support for unionfs

*--*[*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

*--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-*]*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).
	"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.

*crypt_swap*=<...>::
    This specifies the swap device encrypted by Luks.

*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.

*noslowusb*::
    By default genkernel pause for 10 seconds if it finds a attached
    usb-storage device to give them time to initiate.
    This option skips that pause.

*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.

*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*=<...>::
    Specify part for mdadm to start.  This is the relevant code in mdstart:
------------------------------------------
    fd = open("/dev/md<MD_NUMBER>", 0, 0);
    ioctl(fd, RAID_AUTORUN, <MDPART>);
------------------------------------------

*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.

*unionfs*::
*nounionfs*::
    Enables/disables UnionFS.

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

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

*real_resume*=<...>::
*resume*=<...>::
*noresume*::
    *noresume* disables any default resume parameters. *resume* and
    *real_resume* specify a device via LABEL or UUID to use for for loading a
    TuxOnICE, SWSUSP or Suspend2 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.


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