installkernel.8

.TH installkernel 8 "13 January, 2012" "version 17.0" "Linux System Administration"

\"
\" installkernel man page
\" Copyright (c) 2005-2012 by Michal Nazarewicz (mina86/AT/mina86.com)
\"
\" This is part of Tiny Applications Collection
\"   -> http://tinyapps.sourceforge.net/
\"

.SH NAME

\fBinstallkernel\fP \- compiles and installs the Linux kernel.

.SH SYNOPSIS

\fBinstallkernel\fP [<options>] [<switches>]
[\fIversion\fP [\fIimage\fP [\fIsystemmap\fP [\fIprefix\fP]]]]

.SH DESCRIPTION

\fBinstallkernel\fP is a shell script that automates Linux kernel
installation process.  It can automatically compile and install kernel
image and modules and remove old files.  When additional scripts are
added it can also automatically install modules which are not part of
Linux or perform some other tasks specific for local machine.

.PP
It is written in standard compilant way and is believed to run on any
POSIX compatible shell, therefore, it can be used on embeded systems.

.SH ARGUMENTS

.PP
If you use short option which requires an argument (eg. \fB\-a\fP) the
argument must be specified just after the option without whitespace
(eg. \fB\-ai386\fP).  The script also doesn't support joining several
short options in one argument, eg.: \fB\-iImM\fB.

.SS Options
.TP
\fB\-h \-\-help\fP
Displays a help screen and exits

.TP
\fB\-V \-\-version\fP
Displays the version number and exits

.TP
\fB\-a \-\-arch=\fIarch\fP
Sets the \fBARCH\fP environmental variable to \fIarch\fP unless it is
\fB-\fP in which case the environmental variable is left without any
changes.  By default, it is generated from the output of \fBuname
\-m\fP command.

.TP
\fB\-\-bootdir=\fIdir\fP
Specifies the directory where the kernel image will be installed.
For more info see \fB<prefix>\fP.

.TP
\fB\-\-kversion=\fIver\fP
Specifies the kernel version.  For more info see \fIversion\fP.

.TP
\fB\-\-image=\fIimage\fP
Specifies the kernel image.  For more info see \fIimage\fP.

.TP
\fB\-\-map=\fIsystemmap\fP
Specifies the System map file.  For more info see \fIsystemmap\fP.

.TP
\fB\-\-cd[=\fIdir\fB]\fP
The script will attempt to change directory to \fIdir\fP before doing
anything.

.TP
\fB\-\-cd\fP
Synonym of \fB\-\-cd=/usr/src/linux\fP.  Useful for people who keep
their kernel source code in \fI/usr/src/linux\fP.  Can save you from
typing those extra characters. :)

.TP
\fB\-o\ \-\-out[=\fIdir\fB]\fP
The script will set \fBKBUILD_OUTPUT\fP environmental variable
resulting in kernel being built in \fIdir\fP or
\fI/usr/src/linux-build\fP directory if argument was omitted.

Note that there is a\ known issue when using this option where script
is unable to determine kernel version one is building.  As a
workaround one shall use \fB\-\-kversion\fP option as well with full
kernel version specified (ie. \fB\-\-kversion=2.6.30.5\fP or
\fB\-\-kversion=2.6.30.5-myown\fP if you add additional tags).

.TP
\fB\-\-su\fP
If the script was not run as super user it will try to become super
user at the beginning.  Most likely, you will be asked to enter a root
password at the beginning of the script.  The option also implies
\fB\-\-user=\fIcurrent\-user\fP where \fIcurent-user\fP is a username
of user executing the script.

.TP
\fB\-u \-\-user=\fIuser\fP
Runs all commands which do not require super user privileges (this
include cleaning sources, updating dependencies (in 2.4.x) and
compiling image and modules) as \fIuser\fP.

.TP
\fB\-nu \-\-no\-user\fP
This is synonym of \fB\-\-user=\fP.  Useful if you want to do
everything as root and use \fB\-\-su\fP option (not recommended since
you can build image as non-root user without any problems).

.TP
\fB\-\-nice=[\fInice\fB]\fP
If \fInice\fP is a number adds it to a nice value; if it is a number
prefixed by an exclamation mark ("!") sets the nice value to given
number.  The default is "!10".  Setting this to a big value (eg. 20)
is useful on slow machines if you don't want compilation to be
noticeable.  Script will never lower the nice value.

.TP
\fB\-\-no\-nice\fP
Synonym of \fB\-\-nice=0\fP.

.TP
\fB\-j \-\-jobs=\fIjobs\fP
Uses \fIjobs\fP processes when building kernel.  This option simply
passes \fB\-j\fIjobs\fP option to \fBmake\fP command.  The default is
\fBauto\fP which determines number of processors (or cores) by reading
\fB/proc/cpuinfo\fI file and uses that number for \fB\j\fP option.  To
use a\ single process use \fB\-j1\fP.

.TP
\fB\-\-\fP
A\ modifier which changes the way arguments on command line are
interpreted.  If an argument that does not start with a\ dash is found
it is treated as a\ long option, if it is at least 3 character long,
or a\ short option, if it is no more then 2 character long
(effectively prefixing the argument with a\ dash or two dashes).  This
option has been implemented to shorten options.

.TP
\fIversion\fP \fIimage\fP \fIsystemmap\fP
Those are the version (what compiled kernel will raport as
\fBuname -r\fP so it shall include any additional tags), the path to
the kernel image file and path to the kernel map file.  In most cases
they are unnecessary as the script detects all this by itself but they
are provided for compatibility with \fBmake install\fP.  Those
arguments overwrites and can be overwritten (depending on the order in
which arguments are given) \fB\-\-kversion\fP, \fB\-\-image\fP and
\fB-\-map\fP options.

.TP
\fIprefix\fP
Specifies the place where the kernel image should be installed to.  By
default it is \fB/boot\fP unless a \fBINSTALL_PATH\fP environmental
variable is set in which case it's value is taken.  This argument
overwrites and can be overwritten (depending on the order in which
arguments are given) the \fB\-\-bootdir\fP option.


.SS Switches

.TP
\fB\-\-dry\-run\fP
Only prints what would be done.  This implies
\fB\-\-print\-commands\fP.  \fBWARNING\fP In some cases it DO modify
the source tree.  The default is \fBno\fP.

.TP
\fB\-\-print\-commands\fP
Before each command is executed it is first printed to the stdout.
The default is \fBno\fP.

.TP
\fB\-v \-\-verbose\fP
Becomes more verbose.  When turning on implies
\fB\-\-print\-commands\fP but when disabling does not disable
\fB\-\-print\-commands\fP. The default is \fBno\fP.

.TP
\fB\-vv\fP
Becomes a lot more verbose.  When turning on implies \fB\-\-verbose\fP
but when disabling does not disable \fB\-\-verbose\fP.  The default is
\fBno\fP.

.TP
\fB\-\-color\fP
Uses ANSI escape sequences to print messages in color.  By default,
this is on if writing to a terminal.  There are some bugs, however,
so if you use \fB>\fP to log messages use \fB\-\-no\-color\fP option
to be sure.

.TP
\fB\-r\fIhook\fB \-\-run\-\fIhook\fP
If \fIhook\Fp is a\ name of a\ hook runs this hook, if it is a\ name
of an event runs pre-\fIhook\fP and post-\fIhook\fP if it is
"\fBpre-hook\fP" or "\fBpost-hook\fP" runs all pre- or post-hooks, if
it is "\fBhooks\fP" runs all hooks.  See HOOKS section below for more
details.

.TP
\fB\-c \-\-clean\fP
Runs \fBmake clean\fP at the beginning.  The default is \fBno\fP.

.TP
\fB\-C \-\-config\fP
Runs \fBmake *config\fP at the beginning to configure the kernel.  The
default is \fBno\fP.

.TP
\fB\-C \-\-config[=\fItype\fB]\fP
Specifies what type of config the script should run.  It implies
\fB\-\-config\fP or if \fItype\fP is \fIno\fP \fB\-\-no\-config\fP.
By default the script tries to guess what kind of config to run.  If
\fBDISPLAY\fP environmental variable is set and \fBqtconfig\fP program
is available it will assume \fBxconfig\fP.  If \fBDISPLAY\fP is set
and \fBgtk-config\fP is available \fBgconfig\fP will be used.  If it
can find a (n)curses library \fBmanuconfig\fP is the choice.  In all
other cases \fBconfig\fP will be used.

.TP
\fB\-d \-\-make\-dep\fP
Runs \fBmake dep\fP.  The default is to run it if
\fB\-\-compile\-image\fP is on and compiling Linux 2.4.x, however this
is enabled only if \fIversion\fP was given as an argument.

.TP
\fB\-A \-\-all\fP
Synonym of \fB\-\-compile \-\-install \-\-tidy\fP.

.TP
\fB\-i \-\-compile\-image\fP
Runs \fBmake bzImage\fP to compile the kernel image.  The default is
\fBno\fP.

.TP
\fB\-I \-\-install\-image\fP
Installs the kernel image by copying appropriate files to \fB/boot\fP
directory (or other directory specified by \fIprefix\fP or
\fBINSTALL_PATH\fP enviromental varialbe).  It will also update
symlinks in that directory.  By default it is \fByes\fP if exactly 4
arguments are given, and thye are: \fIversion\fP \fIimage\fP
\fIsystemmap\fP \fIprefix\fP, otherwise it is \fBno\fP.

.TP
\fB\-t \-\-tidy\-image\fP
Removes really old kernel images from the \fB/boot\fP directory (or
any other directory given with \fB\-\-bootdir\fP of \fIprefix\fP
options).  The default is \fBno\fP.

.TP
\fB\-\-image\fP
Synonym of \fB\-\-compile\-image \-\-install\-image \-\-tidy\-image\fP.

.TP
\fB\-m \-\-compile\-modules\fP
Runs \fBmake modules\fP to compile the kernel modules.  The default is
\fBno\fP.

.TP
\fB\-M \-\-install\-modules\fP
Runs \fBmake modules_install\fP to install kernel modules.  The
default is \fBno\fP.

.TP
\fB\-T \-\-tidy\-modules\fP
Removes old kernel modules from \fB/lib/modules\fP directory.  The
default is \fBno\fP.

.TP
\fB\-\-modules\fP
Synonym of \fB\-\-compile\-modules \-\-install\-modules
\-\-tidy\-modules\fB.

.TP
\fB\-\-compile\fP
Synonym of \fB\-\-compile\-image \-\-compile\-modules\fP.

.TP
\fB\-\-install\fP
Synonym of \fB\-\-install\-image \-\-install\-modules\fP.

.TP
\fB\-\-tidy\fP
Synonym of \fB\-\-tidy\-image \-\-tidy\-modules\fP.  You should not
use any of the \fB\-\-tidy\fP switches if you do not use corresponding
\fB\-\-install\fP switch as it may leave you with only one kernel or
modules for only one kernel.

.PP
Meaning of a\ switch may be negated by prefixing it with \fBno\-\fP
(if long form is used) or \fBn\fP (if short form is used).  If it is
synonym of several other switches then all those switches will be
turned on or off.

.SH EXIT CODE

\fBinstallkernel\fP defines the fallowing exit code values:

.TP
\fB0\fP
Everything went OK.

.TP
\fB1\fP
Invalid arguments where given.

.TP
\fB2\fP
Some other errors detected by the script.  At the moment, this
includes the situation when kernel version could not be determined.

.TP
\fB3\fP
A condition which should never happen happened.  This is an internal
error and if it occures should be considered as a bug.

.TP
\fB4\fP
A lockfile exists and another instance of \fBinstallkernel\fP is
running.

.TP
\fB5\fP
The script recieved on of the signals: \fBSIGHUP\fP, \fBSIGINT\fP,
\fBSIGQUIT\fP, \fBSIGILL\fP, \fBSIGABRT\fP, \fBSIGFPE\fP,
\fBSIGSEGV\fP, \fBSIGPIPE\fP, \fBSIGALRM\fP, \fBSIGTERM\fP or
\fBSIGTSTP\fP.

.PP
Moreover, if during execution any command fails, \fBinstallkernel\fP
will exit with it's exit code, therefore all the above exit codes can
have a\ few meanings.

.SH HOOKS

Hooks were provided to allow executing of user customizable code which
may be necessary for a particular machine.  For example one could
write a script which automatically installs graphic card drivers after
the kernel modules are installed.  Someone else could write a short
script which reboots the machine after the new kernel is installed or
could kill some resource consuming daemons just before compilation to
run them again after compilation is done.  There are many aspects in
which hooks may be handy.

.PP
There are events and hooks.  Events are: \fBclean\fP, \fBconfig\fP,
\fBmake\-dep\fP, \fBcompile\-image\fP, \fBcompile\-modules\fP,
\fBinstall\-modules\fP, \fBtidy\-image\fP, \fBtidy\-modules\fP,
\fBinstall\-image\fP and \fBwork\fP where each event corresponds to
each step of the \fBinstallkernel\fP script plus the \fBwork\fP event
correspond to whole work done by the script (the old \fBpre\fP and
\fBpost\fP hooks are no longer supported).  Each event has
a \fBpre\-\fP and \fBpost\-\fP hook.  So for example there are
\fBpre\-clean\fP and \fBpost\-clean\fP hooks.

.PP
When a hook is executed \fB/etc/installkernel.d/hook-handler\fP is run
with first argument being hook name (in the future more arguments may
be defined).

.SH LILO CONFIG

After the kernel image is installed (when \fB\-\-install\-image is
true) the new kernel image can be accessed by a \fB/boot/bzImage\fP
and the old one by \fB/boot/bzImage~\fP symlinks.  The same is with
\fBSystem.map\fP and \fBconfig\fP files.  This way you don't have to
alter your LILO configuration each time, so \fBlilo.conf\fP
(\fB/etc/lilo.conf\fP by default) should contain code similar to the
fallowing:

.nf
image = /boot/bzImage
    root = /dev/\fIwhatever\fP
    label = Linux
    read-only

image = /boot/bzImage
    root = /dev/\fIwhatever\fP
    label = Old image
    read-only
.PP

For more details consult lilo.conf(5) man page.

.SH AUTOMATIC LILO UPDATING

In the past, installkernel had an \fB\-\-update\-loader\fP option
which would call lilo to update its configuration.  This has been
since removed and users who need it are urged to use
\fBpost\-install\-image\fP hook.  All that is needed is to create an
executable file under \fB/etc/installkernel.d/hook\-handler\fP with
the following content:

.nf
#! /bin/sh

case "$1" in post-install-image)
	lilo
esac
.PP

This will cause lilo to be run every time kernel image is installed.

.SH EXAMPLES

.TP
\fBinstallkernel \-\-su \-\-cd \-\-all \-\-nice=20\fP
Does everything (compiles the kernel image and modules then installs
them and removes old ones).  At the beginning asks for root password
so when super user privileges are required the script will use them
however everything else will be run as a user who run the script.  The
script will also change the directory to \fB/usr/src/linux\fP for you.

.TP
\fBinstallkernel \-\-su \-\-no\-user \-\-cd \-\-all\fP
Similar to the above but everything will be run as super user (even
build process).

.TP
\fBinstallkernel \-\-su \-\-cd \-\-modules\fP
Will compile, install and tidy the kernel modules only.

.TP
\fBinstallkernel \-\-all \-\-su \-\-cd 2>&1 | tee -a installkernel-log && /sbin/reboot\fP
Something for lazy sysadmins.  This will do everything to get a new
kernel image work and if everything went OK system will reboot.  All
messages will be logged to \fBinstallkernel\-log\fP file for future
analyse.  \fBBeware\fP that it's not very wise to get system
automatically reboot without sysadmin.  You should rather reboot the
system when you get back the next day.  You may however replace
\fB&& /sbin/reboot\fP with \fB; /sbin/halt\fP to run a nightly
compilation.  Note that you have to have \fBreboot\fP and \fBhalt\fP
properly configured for a non\-root user to be able to run.

.SH AUTHOR

Michal Nazarewicz (\fImina86/AT/mina86.com\fP).  See
<\fIhttp://tinyapps.sourceforge.net/\fP> for more info.