Building and Installing Periscope

Periscope was designed into version 2.2.14 of the Linux kernel (hereafter called the Periscope kernel). To use Periscope, you will need to configure, build and install the kernel on your machine. This document is meant to help you through the process of building Periscope and getting it running on your machine.

First Things First

The Linux kernel is only one of many pieces of software needed to run what most people consider Linux; the kernel together with these other pieces make up a Linux disrtibution. If you do not already have a machine that is running Linux, you will need to choose a Linux distribution and install and configure Linux for your machine. The details of this are beyond the scope of this document, but the following HOWTO documents may provide some helpful information:

These and many other useful documents come from The Linux Documentation Project.

Since you will be using this machine to run Periscope, it may simplify things if you choose a distribution (or version of a distribution) that contains a 2.2.x version of the kernel. For instance, Periscope was developed on a RedHat 6.2 machine which uses version 2.2.14 of the Linux kernel. Our experience has been that it is easier to get Periscope running if the version of the kernel being replaced is close to the version of the Persicope kernel.

You should not move on to building the Periscope kernel until you have gotten your machine running as you expect it to. This should at least include configuring the network. Take time to test the services that you expect to use before you begin working on Periscope so that you will know what (if anything) needs to be fixed after you install the new kernel.

Building the Periscope Kernel

Once you have the machine running smoothly, you are ready to begin building the Periscope kernel. You will need the Periscope kernel sources:

Unpack this in an appropriate location on your machine (typically in /usr/src). The file named README in the top level directory of the kernel sources contains brief instructions on building the kernel. The Linux Kernel HOWTO also provides useful information about building the kernel. In developing Periscope, the only change made to the kernel build process was to add a periscope_config target (described below), so any documentation that describes how to build a standard Linux kernel will also apply to building the Periscope kernel (assuming that you add the step to make periscope_config at the appropriate time).

The following steps outline the process of building the kernel and are discussed briefly below. You may use these as a starting point, but please refer to the documentation mentioned above if you encounter difficulties. All of these steps should be executed from the top level of the kernel sources.

> make menuconfig
> make periscope_config
> make dep
> make bzImage
> make modules
> make modules_install
> ... copy and install the kernel image

make menuconfig

This step is where you configure the kernel to support the hardware and services that you plan to use. You should be able to select any combination of options to configure the kernel for your installation. The Periscope code will be configured into the kernel in the next step.

Note: We have found it useful to enable all of the Loadable module support options, but if you know better feel free to ignore this advice.

make periscope_config

make periscope_config is mandatory for building the Periscope kernel. This step configures the kernel to include the Periscope source code. Without this step, you will just have a standard Linux kernel (very useful on its own, but won't allow you to work with Periscope).

make dep

make dep discovers the dependency relationships between the files in the kernel. However, if going back to the make menuconfig step, it is a good idea to make clean and begin again from the make periscope_config step before rerunning the rest of the build steps.

make bzImage

This step builds the kernel, and if you are building for an x86 machine, it places the kernel in arch/i386/boot/bzImage.

make modules
make modules_install

These steps build and install any modules that you may have configured for your kernel in the make menuconfig step.

Caution: If you are running or have installed on your machine another 2.2.14 version of the Linux kernel, you may want to back up the modules directory before executing the make modules_install step. To determine whether this is necessary, go to /lib/modules and see if you have a directory named 2.2.14. This is where make modules_install will copy the new loadable kernel modules. You may want to back this up to be safe.

Copy and Install the Kernel

This requires that you copy the new kernel image (found at arch/i386/boot/bzImage if you are building for an x86 machine) to your /boot directory. It would be a good idea to give it a name unique among the existing kernels in your /boot directory (maybe vmlinuz-2.2.14-periscope??). You must also update your boot loader (usually lilo or grub) so that the boot loader will be able to see the new image and give you the oportunity to boot the Periscope kernel. It is strongly recommended that you not replace your old, working kernel with the new Periscope kernel, but that you use the capabilities of most boot loaders to allow you to select a kernel at boot time. See the documentation and man pages for the boot loader in use on your system for details on how to do this.

If anything goes wrong