GENKERNEL(8)

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.

--[no-]debug-cleanup
    Turns on or off the full post-run cleanup for debug purposes.

  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.

--virtio
    Adds Virtio support to kernel configuration.

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

--kernel-outputdir=<path>
    Save output files outside the source tree. This should be used rather than KBUILD_OUTPUT when you wish to place kernel objects outside of the source tree (eg because cannot write to that directory as the user genkernel is running as).

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

--[no-]nice[=<niceness>]
    Runs the kernel make at the default niceness (reduction in priority) of 10, or in the case of --no-nice, runs the kernel make at normal priority.

  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-]nfs
    Includes or excludes NFS support.

--[no-]microcode
    Includes or excludes early microcode support.

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

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

--[no-]btrfs
    Includes or excludes Btrfs support.

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

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

--[no-]hyperv
    Includes or excludes Microsoft Hyper-V support

--[no-]ssh
    Includes or excludes SSH (dropbear) support for remote LUKS keys.

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

--strip=<all|kernel|modules|none>
    Strip debug symbols from none, all, installed kernel (obsolete) or modules (default).

--no-strip
    Alias for --strip=none.

--[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-]wrap-initrd
    Wrap initramfs using mkimage for u-boot boots. Please note that only certain compression types are supported by mkimage (see manpage).

--[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/INITRAMFS OPTIONS

The following options are some of those available to be passed as kernel parameters from the bootloader. Genkernel will not handle this operation, please refer to your bootloader documentation for a more complete description of each.

This listing is intended to cover most of the options recognized by the ramdisk/initramfs scripts, as well as some of the common options recognized by the kernel itself.

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.

rootdelay[=<...>], rootwait[=<...>]
    Pauses for up to 3 seconds (or specified number of seconds) while waiting for root device to appear during initramfs root scanning.

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.

dobtrfs
    Scan for attached Btrfs devices on bootup.

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_genkernel
    Do not print anything but error and warning messages during the execution of the initramfs init scripts.

quiet
    Implies quiet_genkernel, but also recognized by the kernel to suppress kernel messages.

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.

unionfs, nounionfs
    Enables/disables UnionFS.

aufs
    Enables support for AUFS (if available in the kernel).

aufs.modules=<...>
    Use an alternate location for filesystem overlays to be added on top of the livecd and below the writable tmpfs. Default is /modules/

overlayfs
    Enables support for Overlayfs (if available in the kernel).

overlayfs.modules=<...>
    Use an alternate location for filesystem overlays to be added on top of the livecd and below the writable tmpfs. Default is /modules/

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 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 https://wiki.gentoo.org/wiki/Genkernel 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>

    • Robin H. Johnson <robbat2@gentoo.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>

    • AUFS/Overlayfs by Zero_Chaos <zerochaos@gentoo.org> and likewhoa

SEE ALSO

/etc/genkernel.conf - genkernel configuration file