ch05.xml

<chapter id="LKN-installing">

<title>
Installing and Booting From a Kernel
</title>

<para>
Previous chapters showed you how to download and build your
kernel. Now that you have an executable file -- along with any
modules you built -- it is time to install the kernel and
attempt to boot it.  In this chapter, unlike earlier ones, all of the
commands need to be run as the root user.  This can be done by
prefixing each command with <command>sudo</command>, by using the
<command>su</command> command to become <emphasis>root</emphasis>, or actually by logging
in as <emphasis>root</emphasis>.
</para>

<para>
To see if you have <command>sudo</command> installed and the proper access
set up, do the following:
<screen>
$ <userinput>sudo ls ~/linux/linux-2.6.17.11/Makefile</userinput>
Password:
Makefile
</screen>
Enter either your own password at the password prompt, or the password of
the system administrator (root). The choice depends on how the
<command>sudo</command> command is set up.  If
this is successful, and you see the line containing:
<screen>
Makefile
</screen>
then you can skip to the next section.
</para>

<para>
If <command>sudo</command> is not installed or giving you the proper
rights, then try using the <command>su</command> command:
<screen>
$ <userinput>su</userinput>
Password:
# <userinput>exit</userinput>
exit
$
</screen>
At the password prompt, enter the password of the system administrator
(<emphasis>root</emphasis>).  When the <command>su</command> program successfully accepts the
password, you are transferred to running everything with full root
privileges.  Be very careful while as <emphasis>root</emphasis>, and do only the minimum needed; then exit the program to continue back as your normal user account.
</para>

<sect1>
<title>Using a Distribution's Installation Scripts</title>
<para>
Almost all distributions come with a script called
<command>installkernel</command> that can be used by the kernel build
system to automatically install a built kernel into the proper location and
modify the bootloader so that nothing extra needs to be done by the
developer.
<footnote>
<para>
Notable exceptions to this rule are Gentoo and other "from scratch" types
distributions, which expect users to know how to install kernels on
their own.  These types of distributions include documentation on
how to install a new kernel, so consult it for the exact method
required.
</para>
</footnote>
<note>
<para>
Distributions that offer <command>installkernel</command> usually put it in a
package called <literal>mkinitrd</literal>, so try install that package if you
cannot find the script on your machine.
</para>
</note>
If you have built any modules and want to use use this method to install a kernel, first enter:
<screen>
# <userinput>make modules_install</userinput>
</screen>
This will install all the modules that you have built and place them in
the proper location in the filesystem for the new kernel to properly find.
Modules are placed in the <filename>/lib/modules/</filename><replaceable>KERNEL_VERSION</replaceable>
directory, where <replaceable>KERNEL_VERSION</replaceable> is the kernel version of
the new kernel you have just built.
</para>

<para>
After the modules have been successfully installed, the main kernel image
must be installed:
<screen>
# <userinput>make install</userinput>
</screen>
This will kick off the following process:
<itemizedlist>
<listitem>
<para>
The kernel build system will verify that the kernel has been successfully
built properly.
</para>
</listitem>
<listitem>
<para>
The build system will install the static kernel portion into the <filename>/boot</filename>
directory and name this executable file based on the kernel version of the built kernel.
</para>
</listitem>

<listitem>
<para>
<!--

  AO: I usually see "ramdisk" as one word (including in this book), so
  I'm going to keep that consistent.

-->
Any needed initial ramdisk images will be automatically created, using the
modules that have just been installed during the
<literal>modules_install</literal> phase.
</para>
</listitem>

<listitem>
<para>
The bootloader program will be properly notified that a new kernel is
present, and it will be added to the appropriate menu so the user can
select it the
next the machine is booted.
</para>
</listitem>

</itemizedlist>
</para>

<para>
After this is finished, the kernel is successfully installed, and you can
safely reboot and try out your new kernel image.  Note that this
installation does not overwrite any older kernel images, so if there is a
problem with your new kernel image, the old kernel can be selected at boot
time.
</para>

</sect1>

<sect1>
<title>Installing By Hand</title>

<para>
If your distributtion does not have a <command>installkernel</command> command, or
you wish to just do the work by hand to understand the steps involved, here
are the steps involved.
</para>

<orderedlist>
<listitem>
<para>
The modules must be installed:
<screen>
# <userinput>make modules_install</userinput>
</screen>
</para>
</listitem>

<listitem>
<para>
The static kernel image must be copied into the <filename>/boot</filename>
directory. For an <literal>i386</literal>-based kernel, do the
following:
<screen>
# <userinput>make kernelversion</userinput>
2.6.17.11
</screen>
Note that the kernel version will probably be different for your kernel.
Use this value in place of the text <replaceable>KERNEL_VERSION</replaceable> in
all of the following steps:
<screen>
# <userinput>cp arch/i386/boot/bzImage /boot/bzImage-<replaceable>KERNEL_VERSION</replaceable></userinput>
# <userinput>cp System.map /boot/System.map-<replaceable>KERNEL_VERSION</replaceable></userinput>
</screen>
</para>
</listitem>

<listitem>
<para>
Modify the bootloader so it knows about the new kernel. This involves
editing a configuration file for the bootloader you use, and is
covered later in <xref linkend="LKN-installing-bootloader" /> for the
GRUB and LILO bootloaders.
</para>
</listitem>
</orderedlist>

<para>
If the boot process does not work properly, it's usually because an initial ramdisk image is needed.  To create this properly, use
the steps in the beginning of this chapter for installing a kernel
automatically, because the distribution install scripts know how to properly
create the ramdisk using the needed scripts and tools.  Because each
distribution does this differently, it is beyond the scope of this book to
cover all of the different methods of building the ramdisk image.
</para>

<para>
Here is a handy script that can be used to install the kernel automatically
instead of having to type the previous commands all the time:
<programlisting>
#!/bin/sh
#
# installs a kernel
#
make modules_install

# find out what kernel version this is
for TAG in VERSION PATCHLEVEL SUBLEVEL EXTRAVERSION ; do
    eval `sed -ne "/^$TAG/s/ //gp" Makefile`
done
SRC_RELEASE=$VERSION.$PATCHLEVEL.$SUBLEVEL$EXTRAVERSION

# figure out the architecture
ARCH=`grep "CONFIG_ARCH " include/linux/autoconf.h | cut -f 2 -d "\""`

# copy the kernel image
cp arch/$ARCH/boot/bzImage /boot/bzImage-"$SRC_RELEASE"

# copy the System.map file
cp System.map /boot/System.map-"$SRC_RELEASE"

echo "Installed $SRC_RELEASE for $ARCH"
</programlisting>
</para>

</sect1>

<sect1 id="LKN-installing-bootloader">
<title>Modifying the Bootloader For the New Kernel</title>

<para>
There are two common Linux kernel bootloaders: GRUB and LILO.  GRUB
is the one more commonly used
in modern distributions, and does some things a little more easily than
LILO, but LILO is still seen as well. We'll cover both in this section.
</para>

<para>
To determine which bootloader your system uses, look in the
<filename>/boot/</filename> directory.  If there is a
<filename>grub</filename> subdirectory:
<screen>
$ <userinput>ls -F /boot | grep grub</userinput>
grub/
</screen>
then you are using the GRUB program to boot with.  If
this directory is not present, look for the presence of the
<filename>/etc/lilo.conf</filename> file:
<screen>
$ <userinput>ls /etc/lilo.conf</userinput>
/etc/lilo.conf
</screen>
If this is present, you are using the LILO program
to boot with.
</para>

<para>
The steps involved in adding a new kernel to each of these programs are
different, so follow only the section that corrisponds to the program you
are using.
</para>

<sect2>
<title>GRUB</title>

<para>
To let GRUB know that a new kernel is present, all you need
to do is modify the <filename>/boot/grub/menu.lst</filename> file.
For full details on the structure of this file, and all of the different
options available, please see the GRUB info pages:
<screen>
$ <userinput>info grub</userinput>
</screen>
</para>

<para>
The easiest way to add a new kernel entry to the
<filename>/boot/grub/menu.lst</filename> file is to copy an existing
entry.  For example, consider the following <filename>menu.lst</filename>
file from a Gentoo system:
<programlisting>
timeout 300
default 0

splashimage=(hd0,0)/grub/splash.xpm.gz

title 2.6.16.11
	root (hd0,0)
	kernel /bzImage-2.6.16.11 root=/dev/sda2 vga=0x0305

title 2.6.16
	root (hd0,0)
	kernel /bzImage-2.6.16 root=/dev/sda2 vga=0x0305
</programlisting>
The line starting with the word <literal>title</literal> defines a new
kernel entry, so this file contains two entries.  Simply copy the lines from one instance of the
<literal>title</literal> word to the next one, such as :
<programlisting>
title 2.6.16.11
	root (hd0,0)
	kernel /bzImage-2.6.16.11 root=/dev/sda2 vga=0x0305
</programlisting>
to the end of the file, and edit the version number to contain the version
number of the new kernel you just installed.
<!--

  AO: I thought the following detail was worth some explanation.

-->
The title does not matter, so long as it is unique, but it is
displayed in the boot menu, so you should make it something meaningful. In our example, we installed
the <literal>2.6.17.11</literal> kernel, so the final copy of the file
looks like:
<programlisting>
timeout 300
default 0

splashimage=(hd0,0)/grub/splash.xpm.gz

title 2.6.16.11
	root (hd0,0)
	kernel /bzImage-2.6.16.11 root=/dev/sda2 vga=0x0305

title 2.6.16
	root (hd0,0)
	kernel /bzImage-2.6.16 root=/dev/sda2 vga=0x0305

title 2.6.17.11
	root (hd0,0)
	kernel /bzImage-2.6.17.11 root=/dev/sda2 vga=0x0305
</programlisting>
</para>

<para>
After you save the file, reboot the system and ensure that the new
kernel image's title comes up in the boot menu.  Use the down arrow to
highlight the new kernel version, and press Enter to
boot the new kernel image.
</para>

<!--
	Should I show an example of a SuSE and Fedora grub file here?  They
	are more complex.  If so, can someone send me a Fedora grub file, I
	don't have any around...

	AO: I think one file is enough. I have both Ubuntu and Fedora
	GRUB files, but I think you've said enough for people to be
	able to make their edits.

-->

</sect2>


<sect2>
<title>LILO</title>

<para>
To let LILO know that a new kernel is present, you must modify the
<filename>/etc/lilo.conf</filename> configuration file and then run the
<command>lilo</command> command to apply the changes made to
the configuration file.  For full details on the structure of the
LILO configuration file, please see the
LILO man page:
<screen>
$ <userinput>man lilo</userinput>
</screen>
</para>

<para>
The easiest way to add a new kernel entry to the
<filename>/etc/lilo.conf</filename> file is to copy an existing
entry.  For example, consider the following LILO
configuration file from a Gentoo system:
<programlisting>
boot=/dev/hda
prompt
timeout=50
default=2.6.12

image=/boot/bzImage-2.6.15
	label=2.6.15
	read-only
	root=/dev/hda2

image=/boot/bzImage-2.6.12
	label=2.6.12
	read-only
	root=/dev/hda2
</programlisting>
The line starting with the word <literal>image=</literal> defines a new
kernel entry, so this file contains two entries.  Simply copy the lines from one instance of the
<literal>image=</literal> word to the next one, such as:
<programlisting>
image=/boot/bzImage-2.6.15
	label=2.6.15
	read-only
	root=/dev/hda2
</programlisting>
to the end of the file, and edit the version number to contain the version
number of the new kernel you just installed. The label does not matter, so long as it is unique, but it is
displayed in the boot menu, so you should make it something meaningful. In our example, we installed
the <literal>2.6.17.11</literal> kernel, so the final copy of the file
looks like:
<programlisting>
boot=/dev/hda
prompt
timeout=50
default=2.6.12

image=/boot/bzImage-2.6.15
	label=2.6.15
	read-only
	root=/dev/hda2

image=/boot/bzImage-2.6.12
	label=2.6.12
	read-only
	root=/dev/hda2

image=/boot/bzImage-2.6.17
	label=2.6.17
	read-only
	root=/dev/hda2
</programlisting>
</para>

<para>
After you save the file, run the <filename>/sbin/lilo</filename> program
to write the configuration changes out to the boot section of
the disk:
<screen>
# /sbin/lilo
</screen>
Now the system can be safely rebooted.  The new kernel choice can be seen
in the list of kernels that are available at boot time.  Use the down arrow
to highlight the new kernel version, and press Enter to
boot the new kernel image.
</para>

<!--
	Should I show anything else for lilo?  Almost no one uses it
	anymore, and I don't think I would be able to find a SuSE or RedHat
	lilo configuration file anymore.

	I feel this is a bit short, but I can't think of anything else that
	is needed.  It is sufficient?

	AO: I think this is fine; it really is simple in real life.
-->

</sect2>
</sect1>

<!-- Do we need a "what to do when it goes wrong" section here?  Or are we
out of space?

AO: Besides forgetting to run LILO, the main thing that can go wrong
 is the initrd, and you've already said it's out of scope. I suppose
 people could have problems with modules too, but I think you've
 covered what they need. So you've written enough.

 -->



</chapter>
<!-- vim: set ai tw=72 : -->