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.
*--gconfig*::
Run "make gconfig" after "make oldconfig".
*--xconfig*::
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*::
Don't copy any modules to the ramdisk.
*--all-ramdisk-modules*::
Copy all kernel modules to the initrd.
*--callback*=<...>::
Run the specified arguments in the current environment after the
kernel and modules have been compiled.
*--static*::
This builds 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'.
*--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*::
Disables keymap selection at boot.
*--lvm*::
Add in LVM support from static binaries if they exist on the
system, or compile static LVM binaries if static ones do not
exist.
*--mdadm*::
Include 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.
*--dmraid*::
Include DMRAID support.
*--multipath*::
Include Multipath support
*--iscsi*::
Include 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'.
*--disklabel*::
Include disk label and uuid support in your initrd.
*--luks*::
Add in Luks support from static binaries if they exist on the
system.
*--gpg*::
Add 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*::
Do not include busybox in the initrd or initramfs.
*--unionfs*::
Include support for unionfs
*--netboot*::
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>.
*--postclear*::
Clear 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*=<tbz2>::
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
*--firmware*::
Enable 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.
*--integrated-initramfs*::
Build the generated initramfs into the kernel instead of keeping it as a separate file.
RAMDISK OPTIONS
---------------
The following options can be passed as kernel parameters from the bootloader,
which the ramdisk scripts would recognize.
*real_root*=<...>::
Specifies the device node of the root filesystem to mount.
*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.
*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.
*real_init*=<...>::
Override location of init script, default is "/sbin/init".
*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
*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.tar.gz'.
*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.
*root*=<...>::
Omit or specify as "/dev/ram0".
For other values be sure to know what you're doing.
*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*::
TO BE DOCUMENTED
*cdroot*[=<...>]::
*cdroot_type*=<...>::
TO BE DOCUMENTED
*loop*=<...>::
*looptype*=<...>::
TO BE DOCUMENTED
*isoboot*=<...>::
TO BE DOCUMENTED
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>
- 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>
SEE ALSO
--------
/etc/genkernel.conf - genkernel configuration file