CS 3210 Operating System Design (Linux)

CS 3210 Operating System Design (Linux)

Spring 2003 * College of Computing, Georgia Tech

Project 1: Hello, iPAQ!

DUE: Febuary 2nd Tuesday 12 noon (arrange a demo with TAs on swiki)

Objective:

To begin to familiarize you with the relatively complex environment we will be working with this semester including: the iPAQ, bootloaders, kernel images, host systems, cross-compilers, source trees, IPSEC and wireless.

Grading Criteria (2%): pass/fail (everyone should pass)

This is just a warm-up. For your group demo, you will just demonstrate your modified kernel working with College filesystem resources across a secure IPSEC channel using LAWN (campus wireless). You can discuss any difficulties you had with your TA during the demo and they will ask questions to probe your understanding. You should have either a working demo or a good explanation for a passing grade.

The Project

There are lots of things you need to know before we can start a serious study of the Linux kernel. You need to get a feel for the iPAQ and its various components and accessories. You need to understand the role and function of the iPAQ bootloader (installed version 2.18.48) You can control the bootloader minimally with the iPAQ buttons. More extensive control is available through the 'serial console' interface. You need to know how to download a clean kernel, switch between differnt kernel and flash root filesystem. This is important if you download a bad kernel or damage the currently installed file system. Loading a flash root filesystem is time-consuming but you will probably only need to do this once or twice this semester.

Once you get a working kernel and file system installed, you will be able to login and control iPAQ Linux using the serial console. You are now running the small 'standalone' Familiar distribution that requires no additional resources from the network or a storage card. Next you will locate and copy the large Linux source tree, cross-compile it on a host Linux machine in the Intel lab and download the resulting kernel. When that works you will make a simple modification to the source by adding a kernel print statement (printk) that will appear on the console when the kernel initializes.

Finally we will have you add the pcmcia jacket (pc jacket) and insert and activate the wireless card. You will then authenticate with LAWN and the IPSEC server in the College and mount and access additional resources via the wireless network. At this point you are using what is known as the Intimate distribution. You should be able to start X and invoke graphical applications.

Step 1: Inventory Your Kit

Make sure you have all the goodies you signed for. Each team should have:

iPAQ 3650
leather jacket (to protect screen)
power cable
serial cable
pcmcia jacket
wireless card
diskette with wireless access keys (Ask Tak for them)

Be very careful with your iPAQ. Do NOT drop it! Be careful with the display. The iPAQ displays are easily scratched and are prone to collecting dust and grit around the edges that mar the display. I like to place the leather jacket on top and wrap it with a rubber band to protect the display.

Step 2: Examine Your iPAQ

Notice the four buttons across the bottom and the large button/speaker that serves the function of arrow keys. The top right corner features the power button. Going across the top (right to left) you will find two LEDs and a microphone. Now look at the top of the iPAQ. Press the silver button on the right to pop-out the stylus. In the middle is the IR element. On the left is a headphone plug. The top left side of the iPAQ features a button to start/stop voice recording under WinCE. Now look at the bottom. First notice the long connector across the bottom. This connects PC (pcmcia) and CF (compact flash) cards to the iPAQ via the PC or CF sleeve or jacket. (We have not given you a CF jacket but they are available for purchase separately. It is also possible to get an inexpensive CF-to-PC adapter.) In the upper right of the bottom is a small opening. Press the stylus here to reset the iPAQ. In the center, you will see something that looks like a USB connector but it is a proprietary serial connection. You will connect the serial cable we have provided here. Just to the left of the serial connection, notice a small metal sliding door containing a small plastic slider. Your iPAQ should have this already slide to the left. Sliding this to the right, completely turns off the iPAQ (for example during shipping) and causes the iPAQ to lose the date and time. Be sure that you slide this to the right (off position) if you are not going to use it for awhile. The leftmost connection is for the power supply.

Step 3: Plug-in and Power-on Your iPAQ

Make sure the slider switch on the bottom of the iPAQ is pushed all the way to the left (as you are facing the iPAQ display). Connect the power supply and press the power button in the upper right hand corner. iPAQ battery life is pretty short. You should get in the habit of connecting the power supply whenever you are working on the iPAQ. Bad things can happen when it loses power in the middle of an important operation (like loading the bootloader). You should see the 'splash screen' of the 2.18.48 version of the bootloader. Press the calendar button on the far left of the bottom to keep the bootloader from trying to boot a Linux kernel. Most of the iPAQs handed out do not have a kernel loaded yet.

Step 4: Connect the ipaq to host machine

Connect the serial cable to the iPAQ and to the serial port on a Linux or Windows machine. You may need to try both serial ports on the back of the machine to get the right one. Be careful with the serial cable. The connection (unfortunately) does not 'lock' into place and it is easily disconnected by simple movements. Bring up a terminal emulation program like Hyperterminal (Windows) or minicom (Linux). Make sure the settings on the terminal emulation program are 8-None-1 ( 8N1) and that you set the communication speed to 115200. Also make sure that hardware and software flow control are turned off.

The standard terminal emulation program under Linux is called 'minicom'. It is adequate but the developers obviously aren't spending a lot of time on improving the interface of this particular program! Remember to invoke minicom with the '-o' (o for orange!) option that keeps minicom from sending a modem initialization string to the iPAQ.

minicom -o

Once minicom is running, you get its attention by pressing 'control-a'. Type 'control-a' followed by 'z' to bring up a menu of things you can do. Type 'o' to select 'configuration'. Arrow down and select 'serial port setup'. Make sure the line reads:

115200 8N1

and that both hardware and software flow control are set to 'no'. (This is important or you will see gibberish.) You should select 'save as default' if you can. If you do, you might not have to go through these changes next time you come to the lab. Now return to the terminal emulation window.

Turn on or reboot the iPAQ. Press the 'calendar' button on the iPAQ or hold the space bar to keep the bootloader from trying to boot. You may need to hit ENTER to see the bootloader prompt on your terminal. Try out a few of the bootloader commands (like 'params show') but be careful!

DO NOT try to erase the bootloader or erase the existing bootloader. This will turn your iPAQ into what is known as 'a brick'. We will need to send it back to Compaq to have the bootloader restored

Step 5: Download a Root Filesystem

Read this section all the way through before starting! We will now download a root filesystem across the serial cable. The kernel image will be embedded in the filesystem image. The root image is large ( ~8 Mb ) and will take 40 minutes to download, but you should only need to do this once this semester. You will however be required to compile your kernel image a number of times over this semester.

When Linux boots, it must refer to some initial configuration files (like all those .conf files in /etc). These files are placed into what is known as the 'root filesystem'. The root filesystem is usually fairly small and contains basic systems admin commands, configuration files and executables for the systems demons (like init). The location of this root filesystem is hard coded into the kernel so that it can be found during kernel initialization. On the iPAQ, our root filesystem will be stored in the flash memory or the iPAQ, so we have a 'flash root filesystem'. The filesystem we will be using is known as JFFS2 (Journaling Flash Filesystem 2) and we will study it in more detail later in the course.

We are using a modified version of the Familiar distribution (v0.5.2). The standard familiar distribution can be found on handhelds.org.

Almost all of the resources for this class are provided by a Linux machine named stallion.cc.gatech.edu. Stallion exports various filesystems, team directories, contains the kernel source tree and cross-compiler and runs the IPSEC gateway. stallion exports these resources to all the Linux machines in the College as well as to your iPAQs when they connect via LAWN. Take a look by logging into a Linux machine and cd'ing into /net/hl2/. This directory is 'auto-mounted' and is only listed in /net when you 'touch' it by cd’ing into the directory.) You should see 'remote' directory which contains team directories.

We will download clean root image using the XMODEM facility in minicom (and the bootloader) from the directory:

/net/hl2/remote/home/taklh/. The file that you need to upload to ipaq is familiar-s03-standard.jffs2. On the bootldr prompt, type the command 'load root' and select the file to upload (Ctrl-A, Z, S in minicom). You can use ymodem protocol instead the default xmodem protocol. Type 'set ymodem 1' on the bootldr prompt and the transfer will use the ymodem instead. You should familiar the transfer interface in the terminal emulator that you choose.

If you are working from the College, you should download the files directly from their location on /net/hl2 instead of making local copies which wastes time and disk and introduces the possibility of copy errors.

Minicom Weirdness

It turns out that minicom has a strange interaction with the iPAQ bootloader. You must initiate the transfer really, really fast or the transfer will be very slow or fail altogether L. If you are really, really fast everything will go well. If you are a little bit slow, the host will resend every packet 2 or 3 times, causing very long download times. (This will become prohibitively long when downloading the root filesystem; on the order of 3 hours). If you are really slow you will get an explicit 'timeout' error message from the bootloader.

The preferred way of doing it is before the actual transfer, mimic the transfer commands , go to the directory containing the filesystem image and abort the transfer there ( by pressing the 'Esc' button). Next time, we try to transfer, we will see this directory first and it will make choosing the file easy.

Also, it is important to leave minicom properly. Try not to just kill the process or shutdown the machine. minicom creates lock files in /tmp and if you leave improperly, the next student on the same machine will not be able to execute minicom.

When you get to that point in minicom. Downloading the root filesystem will take 25 minutes or so if you manage to start fast enough. It is also possible to download the kernel and root using Hyperterminal under Windows. It takes a little longer than minicom when minicom is working fast.

You should now be able to reboot you iPAQ and boot the Linux kernel! Press the 'Q' button on the iPAQ when the bootloader comes up or just type 'boot' at the bootloader prompt:

You should see lots and lots of stuff flying past the screen. It's fun to try and decipher some of this. A few error messages are normal but eventually you should get a 'login:' prompt. The only user setup on the iPAQ initially is root (the super user). I will announce the password in class. You should change the root passwd on the iPAQ when you get a chance.

At this stage you are running a very simple 'stand-alone' version of Linux known as the Familiar distribution. It only has some basic tools like pico, grep, and dmesg. Still, you can move around, examine the file hierarchy, see what commands are there and what commands are missing, etc.

You will do most of this step from a host Linux machine in the Intel lab. Basically you will copy the large (~170M) kernel source tree from stallion into your 'team' directory. Each team is assigned a large directory exported by stallion as:

where # is replaced by a number 1-32. When we connect wirelessly, these directories will be mounted on your iPAQ as /home. There is a team 'group' that contains the 3 team members. Make sure that you make files in these directories group readable and writable (the 'umask' command is a convenient way to do this). You will need to coordinate your activities so that team members do not clobber each other's files.

WARNING: Despite the various security mechanisms we are using, these team directories are still considerably less secure than resources in the College, proper. Do not put anything sensitive in these directories. Everyone please be nice.

Change directory into your team directory from a Linux host. Now copy the compressed tarball (tape archive file) to your team directory:

Now you will unzip and extract the kernel source tree from the compressed archive. Use the GNU tar command like this:

This will uncompress (z), extract (x) verbosely (v) the contents of the specified archive file (f). When tar completes (this will take a little time), you should have both the compressed tarball and the source tree in your team directory. The top-level directory linux-2.4.18-rmk3-hh18 contains a single subdirectory named kernel. Change directory into the actual 'kernel' top-level directory. Notice the directories we studied in class along with the official Makefile and a special fixme.sh script which we will use to apply the IPSEC (freeSWAN) patch to the stock source tree.

Incidentally, if these long path names are making it difficult to see anything because your prompt include the current directory, just redefine the prompt environment variable (PS1) like this:

Next you will need to add the cross-compiler to your search path. You might want to do this in your .profile or .kshrc or whatever so it is done automatically each time you login:

Note that the current directory (.) is not on the search path for root for security reasons so you need to always type './' to get at things in the current directory.

You only need to apply the patch once to the source tree! If you have problems, do an extreme clean of the kernel source tree (make mrproper) and try again:

You are now (finally) ready to compile the kernel. All you should need to do at this point is to type 'make':

On your ipaq, change the directory to /boot. Use zmodem to up the newly compiled zImage to the ipaq. Be sure that it won't over write the existed one.

If you want to compile the kernel on your own Linux machine, you can download get the toolchain at /net/hl2/remote/home/taklh/arm-linux-toolchain-current.tar.gz. Uncompress and extract it to the root directory and add the link to /skiff/local in the /usr/local/.

The kernel has a printf like facility named 'printk'. It behaves just like printf but it is possible to include a 'priority' designation to the print. At any given time, the console has a 'print threshold' associated with it. Prints above the threshold are sent to the console. Priorities are associated with a print by pre-pending a string like '<3>' in front of the text to be printed. If you add no priority a 'default priority' is assumed. All printks are logged through a variety of logging daemons. It is possible to access the printk log using the 'dmesg' command. See Rubini pages 97-100 for more details.

Now that you have successfully compiled and downloaded a kernel, we now ask you to modify the kernel by adding a simple printk near the end of start_kernel in init/main.c. Compile, load and run your modified kernel and use the dmesg facility to view the fruits of your labor.

To allow us to access a more fully-featured Linux distribution (Intimate - essentially a Debian distribution), we will use LAWN to connect wirelessly to College resources. These resources will be exported securely across an encrypted and authenticated channel using IPSEC (freeSWAN). Since starting up IPSEC is somewhat complex, we begin by booting a limited kernel (Familiar) and then 'transfer' to the Intimate distribution using the 'pivot_root' system call, recently added to Linux.

Fit the Orinoco PCMCIA wireless card into the sleeve that came in the brown cardboard box.Now fit the iPAQ into this sleeve.There is a power cable splitter so that you can power both the iPAQ and the wireless card sleeve; use it to plug them both into the power source.Connect the serial cable to the iPAQ and desktop machine as before.Don't turn the iPAQ on yet.

Open up minicom with the iPAQ connected to your desktop machine, make sure the minicom settings are correct as explained in Step 5. Start up the iPAQ and login.You should now see the root prompt '#' in minicom.Now we want to connect the iPAQ to the LAWN wireless network.

These files contain a public and private key for your iPAQ and a public key for the IPSEC server. Make sure you can access these files from your desktop machine. One convenient way to do this is to use the 'mcopy' utility:

We will use minicom again to copy these files to the iPAQ but this time we will use the faster 'ZMODEM' protocol, which also allows you to transfer several files at once:

Next we must provide the WEP key so that LAWN access points will talk to us. WEP was intended as a simple form of encryption to avoid wireless 'drive by shootings' where bad guys listen near the edges of campus for useful data on the wireless. This encryption has recently been shown to be vulnerable. We will still need to supply it in a configuration file. I will announce this key in class.

Briefly remove and re-insert the Orinoco wireless card so that the driver will re-read the wireless.opts file.

You will be prompted for your acme account and password. You should now be connected via LAWN. You can run a few simple tests to verify your connectivity. First, try ping'ing a remote host. Second, use the 'ifconfig' command to determine the dynamic IP address you were assigned by LAWN:

Remember you are running as root on the iPAQ so you must specify another account name ( -l) to login remotely. Try to connect to a remote UNIX machine. When you are logged in, type:

So far, we've just connected to LAWN. We still need to activate IPSEC. Do this by typing:

You should see some messages from 'Pluto' the IPSEC/freeSWAN daemon. You can run:

Finally we are ready to securely mount remote filesystems across the wireless and 'switch over' or 'pivot' to the remote root filesystem that will provide access to a richer set of resources in the Intimate distribution. Just execute the script:

You're now read to go! The old root file system can still be accessed via /boot/root on the iPAQ. See 'man pivot_root' on a recent Linux system (this call was very recently added) for more details. Type the 'mount' command to reveal the filesystems currently mounted. You will notice an appreciable delay when touching remote files. NFS does a lot of caching so the first time you touch something, the delay will be longer than subsequent accesses.

Files created as root from the iPAQ in your team directory will not be accessible from College machines. You need to make sure that team files are owned by your 'team group' and that they have group rwx permission (as appropriate). You can ensure group ownership by using the 'newgrp' command when you first login to the iPAQ:

This spawns a new shell in which all newly created files will be owned by the specified group (it essentially does a login). Notice the naming scheme for team groups; notice particularly that the leading character is just 'c' without the 's'. You can ensure that newly created files have group permissions by using the 'umask' command. We will attempt to automate this for you but you may need to do this manually from time to time.

Exiting requires several steps (in reverse order from activation). If you have executed 'newgrp', type 'control-d' to exit the shell. Next change directory into the original root filesystem:

Linux will not unmount 'busy' filesystems. A filesystem is considered busy if any process has a current working directory on that filesystem. You may also need to kill processes started from the remote filesystem before unmounting. Next run the 'disconnect' script that unmounts several remote filesystems:

(Notice the spelling 'umount'.) You are now ready to deactivate the IPSEC services:

At this point you are back running the Familiar distribution with the flash root filesystem. Gracefully terminate Linux by saying:

Many of the steps you went through for this lab only need to be done once. We will provide a brief outline of steps that must be performed each time you log in and out in the P1 write-up. Also we will try to automate as much of the procedure as we can.

Close to the due date, the TAs will post a variety of grading ‘demo’ slots on the class swiki. Please select a time that all team members can be present and look for the designated TA at that time in the Intel lab. You will be asked to show and describe your code and modifications and demonstrate that it is working. (That will be pretty easy for this assignment. Basically show the source of your printk and show that it appears when you boot. Subsequent assignments will be more challenging.) Each team member will also be asked several questions related to project material. The team will be issued a grade based on your overall performance.