Getting comfortable with the projects

Project Setup

There are two parts to setup: establishing your kernel build environment, and establishing your kernel test environment. The department labs have been set up to make this easy, if you work in them. It is also possible to work on, say, your home machine. (High speed connectivity is almost certainly a requirement, though.)

1. Obtaining the Linux Source

   The version of the source we'll be using is on machine forkbomb.cs.washington.edu. The code itself is /cse451/projects/linux-2.6.13.2.tar.bz2. Your should use that copy of the source no matter what -- no matter what platform it is you build on, no matter what year it is, not matter what the latest Linux distribution is, no matter what version you are running, no matter what Google says, etc.

   How you get the source depends on where you want to build it. We strongly recommend that you build it the dedicated course Linux server, forkbomb. It is certainly possible to build it on other systems, but if you want to do that you're on your own to work out any problems. (It isn't hard -- it will most likely just work, assuming you use a PC running Linux. But, we can't diagnose problems remotely.) Note that you must target an i386 machine for your build, though. (So, building the kernel on a Mac is not straightforward.)

2. Your Build Environment

   The only environment we support is forkbomb.cs.

   You can login to forkbomb using SSH. Your home directory on it is your usual/homes/iws/ directory, and it is backed up. However, due to the usual disk space quotas, you will not have enough quota in your home directory to copy and compile a kernel. Instead, we have provided each of you with local disk space. Your local disk space is in /cse451/username, where username is your unix account name. When you make your copy of the linux kernel and when you edit or compile it, you should do so in this local directory, not your home account.

   However, these local directories are not backed up. This means that if the disk crashes, all of the files in your local directory will be blown away. Thus, I strongly recommend that you keep copies of critical files in your home account; in particular, I'd keep a copy of every file that you've edited or created, and copies of the kernel images that you create. (Don't copy the entire kernel source tree, though: only copy changed files).

   1. ssh forkbomb
   2. cd /cse451/username
   3. cp /cse451/projects/linux-2.6.13.2.tar.bz2 . # note that final period
   4. tar xjf linux-2.6.13.2.tar.bz2
   5. ls

   One more detail: your local directory on forkbomb can be accessed from the WinXP machines using a file transfer client. On the lab WinXP machines, you can find a file transfer client at:

   Start->Programs->Internet and Remote Connections->SSH->Secure File Transfer Client

   This is how you will copy a kernel image from your local directory on the Linux servers to the particular WinXP machine that you're using.

3. VMWare Player

   You'll run your modified kernel inside a virtual machine. To do that, you'll need VMWare Player.

   Lab Machines

   It is already set up on lab machines.

   Other PCs (Windows or Linux)

   VMWare Player is available for free by download:

   • Download VMWare Player.
   • Install it.
   • Reboot, if required.
   • You now need to adjust your network settings. On a Windows machine:
     • Start / Settings / Control Panel / Network Connections / VMWare Network Adaptor VMNet1,
     • then Properties,
     • then highlight Internet Protocol(TCP/IP),
     • then Properties button,
     • then select Use the following IP address and put 192.168.93.1 for the IP address and 255.255.255.0 for the subnet mask,
     • then OK until everything is closed.
     On a Linux machine, do whatever it is that gets the same effect. (Sorry, that's the most I can tell you. Ask a TA...)

4. Virtual Machine Definition Files

   VMWare player is an application that creates a virtual machine. To use it, you must supply it with a pre-created definition of that virtual machine.

   • Fetch forkbomb:/cse451/projects/FC4-451-VMImage.tar.bz2 (470MB).
   • Untar it (tar xjf FC4-....) somewhere (1.5GB).

5. Test Your VMWare Setup

   1. Launch VMware Player.
      It will ask for virtual machine definition file. Navigate to the FC4-451 directory and select the file it shows (Other Linux 2.6.x kernel.vmx).

   2. The machine will start booting.
      Click on the main screen to connect your mouse and keyboard to the virtual machine. (Alt+ctrl will release the mouse/keyboard back to your machine.) You'll be offered a menu of kernels to boot. If you do nothing for about 8 seconds, the default kernel (Fedora Core 4) will boot.

   3. Login
      User root, password rootpassword. (The only other account is user guest, password guestpassword.)

   4. Remote connect to the virtual machine
      To make sure the local (physical) machine's networking is properly set up, login to the virtual machine again, this time using ssh from the machine on which VMWare Player is running (i.e., the physical machine sitting next to you). The virtual machine's "name" is 192.168.93.2. An example command-line login is:

      ssh root@192.168.93.2

      Supply the root password ("rootpassword"). Once you've verified that you can connect, log out.

   5. Set a VMPlayer Preference
      (You have to do this at most once, of course.) Click on the Player menu (at the top to the left). Select Preferences. Now select "Power off the virtual machine" under Exit behavior.

   6. Quit
      Shut down the virtual machine gracefully:

      $ shutdown -h 0

The virtual machine configuration we're using has the following important properties:

1. The hard drive has been set to be non-persistent; if you power down the virtual machine, and power it back on (or if you quit and restart VMware), then any changes that have been made to the file system inside VMware/linux will be lost. This is a good thing: it means every time you restart VMware, there is a working kernel available to boot from. However, it also means that when you install your new kernel, you can't power down the virtual machine; instead, you'll software reboot it from inside linux (as described below).

   There is nothing you can do to change this - it's a restriction of the free player that you can't change this setting. (You can, however, set the Preferences exit behavior option to suspend, rather than power off. The next time you launch VMWare Player the machine will be whereever it was when you last stopped the player -- that is, you could imagine having a machine that ran forever that way.)

2. VMware/linux has been configured for host-only networking; this means that VMware/linux can only communicate with the (physical) host that it is running on, rather than the Internet at large. This is a security measure. It turns out you can change this setting, but don't. (At least, don't change it on the lab machines. You can change it on your own machine, but realize that the copy of Linux running in VMWare Player may be as attackable as it would be running on a physical processor. Also, notice that the ROOT PASSWORD is given right here on this public page. It wouldn't take much skill for someone to break into your Linux machine if you allow access from beyond the physical machine it's running on.)

Compiling and running your kernel

Goals

• To familiarize yourself with the class work environment.
• To learn how to build the Linux kernel.
• To learn how to test kernels under VMware.

Setup

This document provides you with step-by-step instructions for building and booting a kernel. For further information on building kernels, refer to the Linux Kernel HOWTO. The VMware web site (http://www.vmware.com/) has further information on VMware.

The Process

For this class, we are using a somewhat old kernel source (version 2.6.13). This is irrelevant from an instructional standpoint, however it sometimes raises incompatibility problems when forkbomb is updated. Recently, the compiler on forkbomb has been updated to a version (4.3.0) that is no longer compatible with our instructional kernel. For this reason, we will be using a slightly older gcc version (4.0.0) for compiling the kernel (the default gcc installed on forkbomb can still be used for other compilations). gcc-4.0.0 can be found at /cse451/projects/bin/gcc, and you will have to update your PATH environment variable, to ensure that you use it.
Please proceed as follows:
Log onto forkbomb using ssh. In the shell where you will do your kernel compilation, type:

• In bash or ksh:

  export PATH=/cse451/projects/bin:$PATH

• Incsh or tcsh):

  setenv PATH /cse451/projects/bin:$PATH

(To check that you are using the correct gcc version, type gcc --version, it should print 4.0.0.)

Then, cd to /cse451/username/linux-2.6.13.2.

Compile the kernel with:

make bzImage

(Note that it is not necessary to run "make configure " or similar options you may read about in other sources of information.) Compiling will take a while (minutes) the first time you do it, but you won't be recompiling every file all the time, so it will go much faster later on.

Assuming compilation is successful, your new kernel image will be created as ./arch/i386/boot/bzImage. (You should see a statement to that effect at the end of the build output.)

Copy the new kernel image from forkbomb to your local, physical machine:

scp forkbomb:/cse451/username/linux-2.6.13.2/arch/i386/boot/bzImage .

(Note the period at the end of that command line.)

Launch VMware Player and bring up the CSE 451 virtual machine. You might as well log in, since you'll need to be logged in during the next step.

Now scp your bzImage from the local, physical machine to the virtual machine, putting it in directory /boot:

scp bzImage root@192.168.93.2:/boot

Restart Linux on the virtual machine:

shutdown -r 0

as root in the VM. When the boot menu comes up (as almost the first thing once the VM starts rebooting), hit the down arrow key to select the bzImage kernel, rather than Fedora Core (2.6.11-1.1369_FC4), and hit enter. The VM will now attempt to boot using your kernel. If all goes well, you'll get to the login screen and will be able to login as root.

• Adding new files to the kernel source tree: If you need to add a new file to the Linux source tree, do it in the following manner:
  • Determine which existing directory the file(s) will live in
  • Edit the Makefile in that directory, and add the name(s) of the .or file(s) that will be created to the definition of O_OBJS.

• To build the kernel, you must be in the top-level source directory (the one containing the file named REPORTING-BUGS).