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*=:: 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*=:: This outputs debugging data to the file . By default this is '/var/log/genkernel.log'. *--*[*no-*]*color*:: Turns on, or off, output in color using escape sequences. *--*[*no-*]*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-*]*gconfig*:: Runs, or does not run "make gconfig" after "make oldconfig". *--*[*no-*]*xconfig*:: Runs, or does not run "make xconfig" after "make oldconfig". *--*[*no-*]*save-config*:: Saves, or does not save the kernel configuration to '/etc/kernels' if the kernel is successfully compiled. *--*[*no-*]*bcache*:: Adds, or skip adding block layer cache (bcache) support to kernel configuration. *--*[*no-*]*hyperv*:: Adds, or skip adding Microsoft Hyper-V support to kernel configuration. *--microcode*[=]:: Adds early microcode loading support for all, only AMD or Intel processors to kernel configuration. *--no-microcode*:: Do not add early microcode loading support to kernel configuration. *--*[*no-*]*virtio*:: Adds, or skip adding VirtIO support to kernel configuration. *--kernel-localversion*=<...>:: Set kernel option CONFIG_LOCALVERSION. Use special value "UNSET" to unset any already set LOCALVERSION. 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. *--*[*no-*]*oldconfig*:: Runs, or does not run, "make oldconfig" before compilation. Specifying *--oldconfig* implies *--no-clean*. *--*[*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. *--*[*no-*]*module-rebuild*:: Runs, or does not run "emerge @module-rebuild" to build out-of-tree modules when possible, i.e. when non-static kernel and modules will be build, installed, no custom INSTALL_MOD_PATH is set, '/var/lib/module-rebuild/moduledb' exists and is not empty. *--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*=:: This specifies the location of the kernel sources; the default is '/usr/src/linux'. *--kernel-config*=:: 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. Use the special value 'default' to force usage of default kernel config. *--module-prefix*=:: Prefix to kernel module destination, modules will be installed in '/lib/modules'. LOW-LEVEL COMPILATION OPTIONS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *--cross-compile*=:: Target triple (i.e. aarch64-linux-gnu) to build for. Only needed when the system running genkernel has a different architecture like the system which should boot the created kernel/initramfs. *--kernel-as*=:: Assembler to use for the kernel compilation. *--kernel-cc*=:: Compiler to use for the kernel compilation (e.g. distcc). *--kernel-ld*=:: Linker to use for the kernel compilation. *--kernel-make*=:: GNU Make to use for the kernel compilation. *--kernel-target*=:: Override default make target (bzImage), note that values like *--kernel-target=* are also valid (useful for Xen based kernel sources). *--kernel-binary*=:: Override default kernel binary path (arch/foo/boot/bar). *--kernel-outputdir*=:: 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-as*=:: Assembler to use for utilities. *--utils-cflags*=:: C compiler flags used to compile utilities. *--utils-cc*=:: Compiler to use for utilities. *--utils-ld*=:: Linker to use for utilities. *--utils-make*=:: GNU Make to use for utilities. *--makeopts*=:: GNU Make options such as -j2, etc. *--*[*no-*]*mountboot*:: Mount, or not, BOOTDIR automatically if mountable. *--bootdir*=:: Set the location of the boot-directory, default is '/boot'. *--modprobedir*=:: Set the location of the modprobe.d-directory, default is '/etc/modprobe.d'. *--*[*no-*]*nice*[=]:: 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*=:: Enable framebuffer splash using . *--splash-res*=:: Select gensplash resolutions to include. *--*[*no-*]*splash*=:: If the extra argument is specified, splash is forced using 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*:: Includes or excludes LVM support. When enabled, this will compile LVM for you. *--*[*no-*]*mdadm*:: Includes or excludes mdadm support. When enabled, this will compile mdadm for you. *--mdadm-config*=:: Use as configfile for MDADM. By default the ramdisk will be built *without* an 'mdadm.conf' and will auto-detect arrays during boot-up. *--*[*no-*]*microcode-initramfs*:: Prepends, or do not prepend ucode(s) to the initramfs. But only when kernel configuration does support early microcode loading. See *--microcode* option to auto-update kernel configuration. *--*[*no-*]*dmraid*:: Includes or excludes DMRAID support. When enabled, this will compile dmraid for you. *--*[*no-*]*nfs*:: Includes or excludes NFS support. *--*[*no-*]*e2fsprogs*:: Includes or excludes e2fsprogs. When enabled, this will compile e2fsprogs for you. *--*[*no-*]*xfsprogs*:: Includes or excludes xfsprogs. When enabled, this will compile xfsprogs for you. *--*[*no-*]*zfs*:: Includes or excludes ZFS support. *--*[*no-*]*btrfs*:: Includes or excludes Btrfs support. When enabled, this will compile btrfs-progs for you. *--*[*no-*]*multipath*:: Includes or excludes Multipath support. When enabled, this will compile multipath-tools for you. *--*[*no-*]*iscsi*:: Includes or excludes iSCSI support. When enabled, this will compile open-iscsi for you. *--*[*no-*]*sandbox*:: Enables or disables sandbox-ing when building initramfs. *--*[*no-*]*ssh*:: Includes or excludes SSH (dropbear) support for remote LUKS keys. When enabled, this will compile dropbear for you. *--ssh-authorized-keys-file*=:: Specifies a user created authorized_keys file. By default genkernel will use '/etc/dropbear/authorized_keys'. *--ssh-host-keys*=:: When set to *create*, which is the default value, genkernel will embed SSH host keys from '/etc/dropbear' and will create those keys when missing. When set to *create-from-host*, genkernel will embed SSH host keys from '/etc/dropbear' but will create those keys from '/etc/ssh' when missing (not recommended for security reasons). When set to *runtime*, genkernel will not embed any SSH host key in initramfs and dropbear will generate needed host key at runtime (`dropbear -R`). *--bootloader*=:: Add new kernel to GRUB or GRUB2 configuration. *--linuxrc*=:: Use for the linuxrc instead of the genkernel linuxrc. *--busybox-config*=:: 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 initramfs. When enabled, this will compile util-linux for you. *--*[*no-*]*luks*:: Includes or excludes LUKS support. When enabled, this will compile cryptsetup for you. *--*[*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 initramfs. When enabled, this will compile busybox for you. *--*[*no-*]*unionfs*:: Includes or excludes support for unionfs. When enabled, this will compile unionfs-fuse for you. *--*[*no-*]*netboot*:: Creates or does not create a self-contained env in the initramfs. *--real-root*=:: Specify a default for *real_root*= kernel option which will be embedded into initramfs. INTERNALS ~~~~~~~~~ *--cachedir*=:: Override the default cache location. *--check-free-disk-space-bootdir*=:: When set to a non-zero value, genkernel will check early on start for specified amount of free disk space in megabyte in *BOOTDIR*. *--check-free-disk-space-kerneloutputdir*=:: When set to a non-zero value, genkernel will check early on start for specified amount of free disk space in megabyte in *KERNEL_OUTPUTDIR*. *--*[*no-*]*clear-cachedir*:: Clears or skips clearing all files in cache location on genkernel start. *--tmpdir*=:: Sets genkernel's temporary working directory to . By default, a directory below '/var/tmp/genkernel' will be used. *--*[*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*=:: Archive file created using tar containing kernel and initramfs. NOTE: No modules outside of the initramfs will be included! *--modulespackage*=:: Archive file created using tar containing modules after the callbacks have run. *--kerncache*=:: Archive file created using tar containing kernel binary, content of '/lib/modules' and the kernel config after the callbacks have 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*=:: 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*=:: Specify directory to copy firmware from (defaults to '/lib/firmware'). *--firmware-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*:: Compresses or does not compress the generated initramfs. *--*[*no-*]*compress-initrd*:: Deprecated alias for *--*[*no-*]*compress-initramfs*. *--compress-initramfs-type*=:: 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. *--strip*=:: Strip debug symbols from none, all, installed kernel (obsolete) or modules (default). *--no-strip*:: Alias for *--strip=none*. 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 'https://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 which can be specified using *gk.net.iface* kernel parameter. By default, dhcp will be used. You can set a specific IP address using addr/CIDR notation, i.e. '1.2.3.4/24'. *gk.net.dhcp.retries*=<...>:: By default we will send up to 3 DHCP discovery requests. *gk.net.iface*=:: By default we will use the interface named eth0. Use this kernel parameter to specify another interface. You can also specify a MAC address (00:00:00:00:00:00 format) instead of an interface name. *gk.net.gw*=<...>:: Optional gateway. If *ip* is set to dhcp, this kernel parameter will be ignored. *gk.net.routes*=<...>:: Optional additional routes. If *ip* is set to dhcp, this kernel parameter will be ignored. *gk.net.timeout.dad*=<...>:: By default we will wait up to 10 seconds for IPv6's DAD to complete. At the moment, we only wait for DAD while bringing down an interface to prevent a race condition. *gk.net.timeout.deconfiguration*=<...>:: By default we will wait up to 10 seconds while bringing down an interface to prevent a race condition. *gk.net.timeout.dhcp*=<...>:: By default we will wait up to 10 seconds for a DHCP server reply. *gk.net.timeout.interface*=<...>:: By default we will wait up to 10 seconds for interface to show up. *dosshd*:: Will start an SSH daemon within initramfs allowing to remotely unlock encrypted devices or just for debugging purpose. *gk.sshd.port*=<...>:: By default, sshd will listen on port 22. *gk.sshd.wait*=<...>:: Wait X seconds after setting up sshd, useful when you want to login (and thus pause boot process) before booting real system. *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*[=cache,force]:: Scan for bootable ZFS pools on bootup. Optionally use cachefile or force import if necessary or perform both actions. *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 "/" instead of "/". 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 -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 - Eric Edgar - Chris Gianelloni - Sebastian Pipping - Robin H. Johnson - Thomas Deutschmann - NFS Support by Thomas Seiler - GnuPG 1.x integration by dacook - MDADM integration by Matthias Dahl - ZFS integration by Richard Yao - AUFS/Overlayfs by Zero_Chaos and likewhoa SEE ALSO -------- '/etc/genkernel.conf' - genkernel configuration file // vim: ft=asciidoc et tw=72 sts=4 ts=4 :