path: root/genkernel.8

'\" t
.\"     Title: genkernel
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.0 <http://docbook.sf.net/>
.\"      Date: 05/26/2011
.\"    Manual: genkernel 3.4.15-r1-funtoo
.\"    Source: genkernel 3.4.15-r1-funtoo
.\"  Language: English
.\"
.TH "GENKERNEL" "8" "05/26/2011" "genkernel 3\&.4\&.15\-r1\-funt" "genkernel 3\&.4\&.15\-r1\-funt"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
genkernel \- the Gentoo Linux automatic kernel compiler\&.
.SH "SYNOPSIS"
.sp
\fBgenkernel\fR [options\&...] action
.SH "INTRODUCTION"
.sp
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\&.
.sp
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\&.
.SH "USAGE"
.sp
All that is needed to run genkernel is just genkernel with an action and any flags you might need:
.sp
.if n \{\
.RS 4
.\}
.nf
# genkernel \-\-menuconfig \-\-no\-clean \-\-no\-install all
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.SH "ACTIONS"
.sp
An action tells genkernel what you want it to do \- the following actions are supported:
.PP
\fBall\fR
.RS 4
Build all steps \- the kernel, modules, and the ramdisk\&.
.RE
.PP
\fBbzImage\fR
.RS 4
Build only the kernel\&.
.RE
.PP
\fBinitramfs\fR
.RS 4
Build only the ramdisk/initramfs\&.
.RE
.PP
\fBkernel\fR
.RS 4
Build only the kernel and the modules\&.
.RE
.PP
\fBramdisk\fR
.RS 4
Build only the ramdisk/initramfs\&.
.RE
.SH "OPTIONS"
.sp
Genkernel supports the following options which alter its behaviour\&. Certain options have \fB\-\-no\-\fR variants which do the opposite thing\&. You can specify your options in any order\&.
.SS "CONFIGURATION OPTIONS"
.PP
\fB\-\-config\fR=<file>
.RS 4
Genkernel configuration file to use
.RE
.SS "DEBUGGING OPTIONS"
.PP
\fB\-\-loglevel\fR=<0\-5>
.RS 4
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\&.
.RE
.PP
\fB\-\-logfile\fR=<outfile>
.RS 4
This outputs debugging data to the file <outfile>\&. By default this is
\fI/var/log/genkernel\&.log\fR\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBcolor\fR
.RS 4
Turns on, or off, output in color using escape sequences\&.
.RE
.SS "KERNEL CONFIGURATION"
.PP
\fB\-\-\fR[\fBno\-\fR]\fBmenuconfig\fR
.RS 4
Runs, or does not run "make menuconfig" after running "make oldconfig"\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBsave\-config\fR
.RS 4
Saves, or does not save the kernel configuration to
\fI/etc/kernels\fR
if the kernel is successfully compiled\&.
.RE
.PP
\fB\-\-gconfig\fR
.RS 4
Run "make gconfig" after "make oldconfig"\&.
.RE
.PP
\fB\-\-xconfig\fR
.RS 4
Run "make xconfig" after "make oldconfig"\&.
.RE
.SS "KERNEL COMPILATION"
.PP
\fB\-\-\fR[\fBno\-\fR]\fBclean\fR
.RS 4
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
\fB\-\-no\-clean\fR
implies
\fB\-\-no\-mrproper\fR\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBmrproper\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBinstall\fR
.RS 4
Installs, or does not install the kernel to
\fI/boot\fR
after building\&. The default is
\fB\-\-install\fR\&. If MOUNTBOOT is set in
\fI/etc/genkernel\&.conf\fR
then
\fI/boot\fR
will be automatically mounted if it is not already mounted before the ramdisk and kernel images are copied over\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBsymlink\fR
.RS 4
Manages, or does not manage, symlinks in
\fI/boot\fR
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
\fB\&.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\fR
does nothing unless
\fB\-\-install\fR
is also specified\&.
.RE
.PP
\fB\-\-oldconfig\fR
.RS 4
Implies
\fB\-\-no\-clean\fR, and thus
\fB\-\-no\-mrproper\fR, running a "make oldconfig"\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBsplash\fR
.RS 4
Installs, or not, framebuffer splash support into initramfs\&.
.RE
.PP
\fB\-\-no\-ramdisk\-modules\fR
.RS 4
Don\(cqt copy any modules to the ramdisk\&.
.RE
.PP
\fB\-\-all\-ramdisk\-modules\fR
.RS 4
Copy all kernel modules to the initrd\&.
.RE
.PP
\fB\-\-callback\fR=<\&...>
.RS 4
Run the specified arguments in the current environment after the kernel and modules have been compiled\&.
.RE
.PP
\fB\-\-static\fR
.RS 4
This builds a monolithic kernel without any modules on any initial ramdisks\&.
.RE
.SS "KERNEL LOCATIONS"
.PP
\fB\-\-kerneldir\fR=<dir>
.RS 4
This specifies the location of both the kernel sources and the location to use for building the kernel\&. It defaults to
\fI/usr/src/linux\fR\&. Note that Funtoo Linux genkernel now allows these locations \(em source and build directory \(em to be set separately\&. See \-\-build\-src and \-\-build\-dst below\&.
.RE
.PP
\fB\-\-build\-src\fR=<dir>
.RS 4
This specifies the location of the kernel sources to be built\&. It defaults to the \-\-kerneldir setting if not specified\&.
.RE
.PP
\fB\-\-build\-dst\fR=<dir>
.RS 4
This specifies the location of the target directory in which to build the kernel sources\&. It defaults to the \-\-build\-src setting if not specified\&.
.RE
.PP
\fB\-\-kernel\-config\fR=<file>
.RS 4
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\(cqt a previous config\&.
.RE
.PP
\fB\-\-module\-prefix\fR=<dir>
.RS 4
Prefix to kernel module destination, modules will be installed in
\fI<prefix>/lib/modules\fR\&.
.RE
.SS "LOW\-LEVEL COMPILATION OPTIONS"
.PP
\fB\-\-kernel\-cc\fR=<compiler>
.RS 4
Compiler to use for the kernel compilation (e\&.g\&. distcc)\&.
.RE
.PP
\fB\-\-kernel\-as\fR=<assembler>
.RS 4
Assembler to use for the kernel compilation\&.
.RE
.PP
\fB\-\-kernel\-ld\fR=<linker>
.RS 4
Linker to use for the kernel compilation\&.
.RE
.PP
\fB\-\-kernel\-cross\-compile\fR=<cross var>
.RS 4
CROSS_COMPILE kernel variable\&.
.RE
.PP
\fB\-\-kernel\-make\fR=<makeprg>
.RS 4
GNU Make to use for the kernel compilation\&.
.RE
.PP
\fB\-\-utils\-cc\fR=<compiler>
.RS 4
Compiler to use for utilities\&.
.RE
.PP
\fB\-\-utils\-as\fR=<assembler>
.RS 4
Assembler to use for utilities\&.
.RE
.PP
\fB\-\-utils\-ld\fR=<linker>
.RS 4
Linker to use for utilities\&.
.RE
.PP
\fB\-\-utils\-make\fR=<makeprog>
.RS 4
GNU Make to use for utilities\&.
.RE
.PP
\fB\-\-utils\-cross\-compile\fR=<cross var>
.RS 4
CROSS_COMPILE utils variable\&.
.RE
.PP
\fB\-\-utils\-arch\fR=<arch>
.RS 4
Force to arch for utils only instead of autodetect\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBmountboot\fR
.RS 4
Mount, or not, BOOTDIR automatically if mountable\&.
.RE
.PP
\fB\-\-bootdir\fR=<dir>
.RS 4
Set the location of the boot\-directory, default is
\fI/boot\fR\&.
.RE
.PP
\fB\-\-makeopts\fR=<makeopts>
.RS 4
GNU Make options such as \-j2, etc\&.
.RE
.SS "INITIALIZATION"
.PP
\fB\-\-splash\fR=<theme>
.RS 4
Enable framebuffer splash using <theme>\&.
.RE
.PP
\fB\-\-splash\-res\fR=<resolutions>
.RS 4
Select gensplash resolutions to include\&.
.RE
.PP
\fB\-\-\fR[\fBno\-\fR]\fBsplash\fR=<theme>
.RS 4
If the extra argument is specified, splash is forced using <theme> rather than the default theme specified in your splash configuration\&. If
\fB\-\-no\-splash\fR
is specified, then splash is disabled\&.
.RE
.PP
\fB\-\-do\-keymap\-auto\fR
.RS 4
Force keymap selection at boot\&.
.RE
.PP
\fB\-\-no\-keymap\fR
.RS 4
Disables keymap selection at boot\&.
.RE
.PP
\fB\-\-evms\fR
.RS 4
Add in EVMS support from static binaries if they exist on the system: you should run "emerge evms" first (in the host system)\&.
.RE
.PP
\fB\-\-lvm\fR
.RS 4
Add in LVM support from static binaries if they exist on the system, or compile static LVM binaries if static ones do not exist\&.
.RE
.PP
\fB\-\-mdadm\fR
.RS 4
Include mdadm/mdmon support\&. Without sys\-fs/mdadm[static] installed, this will compile mdadm for you\&.
.RE
.PP
\fB\-\-mdadm\-config\fR=<file>
.RS 4
Use <file> as configfile for MDADM\&. By default the ramdisk will be built
\fBwithout\fR
an mdadm\&.conf and will auto\-detect arrays during boot\-up\&.
.RE
.PP
\fB\-\-dmraid\fR
.RS 4
Include DMRAID support\&.
.RE
.PP
\fB\-\-multipath\fR
.RS 4
Include Multipath support
.RE
.PP
\fB\-\-iscsi\fR
.RS 4
Include iSCSI support
.RE
.PP
\fB\-\-bootloader\fR=\fBgrub\fR
.RS 4
Add new kernel to GRUB configuration\&.
.RE
.PP
\fB\-\-linuxrc\fR=<file>
.RS 4
Use <file> for the linuxrc instead of the genkernel linuxrc\&.
.RE
.PP
\fB\-\-busybox\-config\fR=<file>
.RS 4
Specifies a user created busybox config\&.
.RE
.PP
\fB\-\-genzimage\fR
.RS 4
Make and install kernelz image from
\fIarch/powerpc/boot/zImage\&.initrd\fR\&.
.RE
.PP
\fB\-\-disklabel\fR
.RS 4
Include disk label and uuid support in your initrd\&.
.RE
.PP
\fB\-\-luks\fR
.RS 4
Add in Luks support from static binaries if they exist on the system\&.
.RE
.PP
\fB\-\-gpg\fR
.RS 4
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
\fBroot_key\fR
argument to the new \&.gpg file\&.
.RE
.PP
\fB\-\-no\-busybox\fR
.RS 4
Do not include busybox in the initrd or initramfs\&.
.RE
.PP
\fB\-\-unionfs\fR
.RS 4
Include support for unionfs
.RE
.PP
\fB\-\-netboot\fR
.RS 4
Create a self\-contained env in the initramfs
.RE
.PP
\fB\-\-real\-root\fR=<foo>
.RS 4
Specify a default for
\fBreal_root\fR= kernel option\&.
.RE
.SS "INTERNALS"
.PP
\fB\-\-arch\-override\fR=<arch>
.RS 4
Force the architecture settings described by the <arch> profile instead of autodetecting the running architecture\&.
.RE
.PP
\fB\-\-cachedir\fR=<dir>
.RS 4
Override the default cache location\&.
.RE
.PP
\fB\-\-tempdir\fR=<dir>
.RS 4
Sets genkernel\(cqs temporary working directory to <dir>\&.
.RE
.PP
\fB\-\-postclear\fR
.RS 4
Clear all tmp files and caches after genkernel has run\&.
.RE
.SS "OUTPUT SETTINGS"
.PP
\fB\-\-kernname\fR=<\&...>
.RS 4
This option is used to change part of the suffix appended to the kernel and initrd that defaults to "genkernel"\&. The full suffix is set by the \-\-fullname option \(em see below\&. Note that in Funtoo Linux, this is considered a somewhat deprecated option and \-\-fullname should typically be used instead\&.
.RE
.PP
\fB\-\-fullname\fR=<\&...>
.RS 4
This option is used to set the full suffix for the kernel and initrd/initramfs\&. It is appended to the kernel and initramfs with a hyphen\&. This option defaults to kernname\-arch\-KV where kernname is the \-\-kernname setting, or "genkernel" if not set and KV is the version of the kernel from the kernel MAKEFILE with the EXTRAVERSION from the kernel Makefile appended to it\&.
.RE
.PP
\fB\-\-minkernpackage\fR=<tbz2>
.RS 4
File to output a \&.tar\&.bz2\(cqd kernel and initrd: no modules outside of the initrd will be included\&...
.RE
.PP
\fB\-\-modulespackage\fR=<tbz2>
.RS 4
File to output a \&.tar\&.bz2\(cqd modules after the callbacks have run
.RE
.PP
\fB\-\-kerncache\fR=<tbz2>
.RS 4
File to output a \&.tar\&.bz2\(cqd kernel, contents of
\fI/lib/modules/\fR
and the kernel config\&. NOTE: This is created before the callbacks are run\&.
.RE
.PP
\fB\-\-no\-kernel\-sources\fR=<tbz2>
.RS 4
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\&.
.RE
.PP
\fB\-\-initramfs\-overlay\fR=<dir>
.RS 4
Directory structure to include in the initramfs, only available on 2\&.6 kernels
.RE
.PP
\fB\-\-firmware\fR
.RS 4
Enable copying of firmware into initramfs\&.
.RE
.PP
\fB\-\-firmware\-dir\fR=<dir>
.RS 4
Specify directory to copy firmware from (defaults to
\fI/lib/firmware\fR)\&. Deprecated\&. Use \-\-firmware\-src instead\&.
.RE
.PP
\fB\-\-firmware\-dst\fR=<dir>
.RS 4
Specify directory to copy firmware to (defaults to
\fI/lib/firmware\fR)\&.
.RE
.PP
\fB\-\-firmware\-src\fR=<dir>
.RS 4
Specify directory to copy firmware from\&. Defaults to the value of \-\-firmware\-dst\&.
.RE
.PP
\fB\-\-firmware\-files\fR=<files>
.RS 4
Specifies specific firmware files to copy\&. This overrides
\fB\-\-firmware\-dir\fR\&. For multiple files, separate the filenames with a comma\&.
.RE
.PP
\fB\-\-integrated\-initramfs\fR
.RS 4
Build the generated initramfs into the kernel instead of keeping it as a separate file\&.
.RE
.SH "RAMDISK OPTIONS"
.sp
The following options can be passed as kernel parameters from the bootloader, which the ramdisk scripts would recognize\&.
.PP
\fBreal_root\fR=<\&...>
.RS 4
Specifies the device node of the root filesystem to mount\&.
.RE
.PP
\fBcrypt_root\fR=<\&...>
.RS 4
This specifies the device encrypted by Luks, which contains the root filesystem to mount\&.
.RE
.PP
\fBcrypt_swap\fR=<\&...>
.RS 4
This specifies the swap device encrypted by Luks\&.
.RE
.PP
\fBroot_key\fR=<\&...>
.RS 4
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\&.
.RE
.PP
\fBroot_keydev\fR=<\&...>
.RS 4
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\&.
.RE
.PP
\fBswap_key\fR=<\&...>
.RS 4
Same as root_key for swap\&.
.RE
.PP
\fBswap_keydev\fR=<\&...>
.RS 4
Same as root_keydev for swap\&.
.RE
.PP
\fBcrypt_silent\fR
.RS 4
Set this to silent all the output related to the cryptographic software, and in case your encrypted device isn\(cqt open with the key, it opens a shell in the initrd quietly\&.
.RE
.PP
\fBdodmraid\fR=<\&...>
.RS 4
Passes arguments to dmraid on bootup\&.
.RE
.PP
\fBreal_init\fR=<\&...>
.RS 4
Passes arguments to init on bootup\&.
.RE
.PP
\fBscandelay\fR=<\&...>
.RS 4
Pauses for 10 seconds before running devfsd if no argument is specified; otherwise pauses for the number of specified seconds\&.
.RE
.PP
\fBip\fR=<\&...>
.RS 4
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\&.
.RE
.PP
\fBnfsroot\fR=<\&...>
.RS 4
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)
.RE
.PP
\fBdoevms\fR
.RS 4
Activate EVMS volumes on bootup
.RE
.PP
\fBdolvm\fR
.RS 4
Activate LVM volumes on bootup
.RE
.PP
\fBdoscsi\fR
.RS 4
Activate SCSI devices on bootup, necessary when SCSI support is compiled as modules and you\(cqre using SCSI or SATA devices\&.
.RE
.PP
\fBnoslowusb\fR
.RS 4
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\&.
.RE
.PP
\fBkeymap\fR=\fIMAP\fR
.RS 4
Set keymap to
\fIMAP\fR, e\&.g\&.
\fBkeymap\fR=de\&. For valid values of
\fIMAP\fR
please see
\fI/usr/share/genkernel/defaults/keymaps\&.tar\&.gz\fR\&.
.RE
.PP
\fBdokeymap\fR
.RS 4
Use keymap\&. Usage of
\fBkeymap\fR= implies this option, already\&.
.RE
.SH "NETBOOTING"
.sp
The initrd scripts have limited support for network booting\&. This is activated if the \fBip\fR=<\&...> kernel parameter was given\&. Please refer to the genkernel guide at \fIhttp://www\&.gentoo\&.org/doc/en/genkernel\&.xml\fR for more information\&.
.sp
The initrd scripts will extract any *\&.tar\&.gz files found in the \fI/add\fR 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\&.
.SH "REPORTING BUGS"
.sp
If you believe you have found a bug in the genkernel scripts, then please file a bug on the funtoo\-dev mailing list (see http://www\&.funtoo\&.org)\&.
.SH "AUTHORS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Daniel Robbins <drobbins@funtoo\&.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tim Yamin <plasmaroo@gentoo\&.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Eric Edgar <rocket@gentoo\&.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
NFS Support by Thomas Seiler <thseiler@gmail\&.com>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GnuPG 1\&.x integration by dacook <schism@subverted\&.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MDADM integration by Matthias Dahl <ua_bugz_gentoo@mortal\-soul\&.de>
.RE
.SH "SEE ALSO"
.sp
/etc/genkernel\&.conf \- genkernel configuration file