TDTS06 Computer Networks

The lab series: Getting started

Installing the lab environment and x-kernel

You will start by setting up the x-kernel environment, verify that it works, learn how to compile a running instance of x-kernel, and experiment with the skeleton of the RDT protocol. The skeleton is actually the ASP protocol (see x-kernel documentation on the Lab assignment page) and you will extend this with the mechanisms for a reliable data transfer protocol

X-kernel was developed by Larry Peterson and colleagues at the University of Arizona. It was explicitly designed to help out network programmers who are not operating system experts. It provides network-centric abstractions and interfaces, and thereby makes it possible for protocol implementers to concentrate on the algorithms that make up network software. By using x-kernel, you can actually define, implement and test actual networking protocols.

The TDTS06 course responsible have already downloaded, built and installed the x-kernel software distribution and libraries required for running x-kernel at IDA. However, you need to initialize your computer account at IDA for the TDTS06 Computer Networks lab series. The following contains a step-by-step description of how to run the standard x-kernel starter program.

Now log in to your IDA account. Make a backup copy of the file .login (dot login) in your home directory. Then, edit the .login file and add the following line just after the module lin in the login file:
```
setenv PATH /home/TDTS06/xkernel/bin/solaris-sparc:/home/TDTS06/bin:$HOME/TDTS06:$PATH
```
Then, log out and do a new login. This will put the TDTS06 lab files in your command path.
When you have logged in again, open a shell window and issue the following command:
```
initTDTS06
```
This will install the necessary lab files in a directory named TDTS06 in your home directory. The TDTS06 directory will contain subdirectories for lab 1, lab 2, lab 3 and lab 4, in addition to the directories for the client and server. There is also a directoyr named asp.
The TDTS06 directory is where you build instances or configurations of the x-kernel for the computer networks labs, so it is also called the build directory in the instructions that follow. The directories are as follows:
- asp contains the example protocol that is used in the tutorial session for the x-kernel as well as referenced in the x-kernel tutorial. In lab 1 you will start with this code, but first after replacing every occurrence of "asp" and "ASP" with "rdt" and "RDT", respectively (more about this in lab 1).
- lab1 contains the starting files for lab 1. The rdttest.c file is the test program that calls the RDT protocol to transfer a file. The test program reads a text file as input and sends chunks of it as messages to the RDT protocol object.
- lab2, lab3 and lab4 are the directories where you will put the solutions for the respective lab assignments
- server and client, respectively, contain information for running the client and server, and are used every time that you start each instance of the current protocol that you are testing and developing in each lab. The rom files roughly correspond to the network card in an ordinary computer. The files contain important information about the ip address and the port number that the client and the server, respectively, need to use in order to run your protocol correctly over the network.
The other directories are initially empty and you will be filling them with code files when you do the different parts of the lab series in the course.
There are two more important files in the TDTS06 directory:
- The graph.comp file contains the protocol graph (or protocol stack, if you like) for your network software. Initially, it is configured to run the ASP protocol (the graph.comp file is a copy of the asp-graph.comp file in the asp directory). You will need to replace the ASP protocol in the protocol stack with your RDT protocol when you start doing the labs (read more in lab 1).
- The Makefile is used when you create new instances of the binary file xkernel
You are now ready to compile the x-kernel, in order to start developing and experimenting with network protocols. Open up a shell (terminal window), then go to the TDTS06 directory (the build directory) in your home directory and issue the command:
```
make first
```
This will update the IP addresses in the rom files for the server and client, respectively, and also configure the protocols according to your graph.comp file. It will compile and link a new executable version of x-kernel for you. You will see a lot of text scrolling by, including some warnings and error messages about missing files, e.g., Makefile.local and DEPS/Makedep.*. You can ignore these.
After the compilation, check that you now have an executable binary file called xkernel in your build directory (approximately 822 KB large), that is, the TDTS06 directory in your home directory. If you get strange errors and no xkernel binary, please first see the Lab FAQ on the course web site and then contact your lab assistant for help.
If everything above seems all right, then run the following command:
```
rehash
```
This till update and refresh the path environmental variable to include the newly added and installed directories and xkernel binary.
Note: Everytime from now on, when you first log in during lab sessions, you must run make first, in order to initialize the rom files in your x-kernel with the correct IP addresses of your current machine (the Sun server that you are connected to with the SunRay thin client). During the rest of the lab session you then can use the command make again in order to recompile x-kernel on the same machine.
The final installation step is to set the port numbers for the client and server, respectively. This information is stored in the rom files. First, edit the rom file for the server in the directory with the same name, using your favourite text editor. For example: If you are sitting at the machine named su15-5, your rom file for the client may look something like this:
```
# The SIMETH line identifies the UDP port that this simulated host
# should use to simulate an ethernet device.

simeth 	9876

...

# One of the real port numbers should correspond to the port number in
# the preceding SIMETH line.
#
#   simulated        Real               Real
#   IP address       IP address         Port number
arp 128.1.2.3        130.236.186.156    1234
arp 128.1.2.4        130.236.186.156    9876
#
```
The simeth line, with the port number 9876 in this case, corresponds to the hardware address of the client. The two arp lines further below denote the mapping of each of the communicating machine's ip address to a port number. The first arp line is the server's ip simulated address, real ip address, and port number. The second arp line is for the client. Note that the port number on the last line should be the same as on the simeth line above for the client. In the rom file for the server, the port number on the first arp line should be the same as the one on the simeth line.
The following is important. Make a backup copy of the rom file. You must then edit the original rom file in three places and first replace the number 1234 with your own unique number, and then replace another number 9876 with your own, but different from the first, unique number, as explained as follows. First, change the number in the last column in each of the lines that start with "arp": Insert a unique port number instead of "1234" and "9876", respectively. The first arp line that you are changing corresponds to the server process, and the second line the client process. Make sure these two numbers are different and unique. We suggest that you take the four last numbers in your and your lab partner's social security number, respectively (replace any letter with a number of your choice), and use them as the two port numbers. However, make sure that they are each larger than 1024 (if you wonder why, see chapter 2 in the textbook).
Then, change the port number on the preceding simeth line: In the server's rom file, this line must contain the port number you chose for the first arp line, and in the client's rom file, the simeth line must contain the port number that you chose to use for the first arp line in the same rom file. Make sure you see the pattern of how these numbers are placed in the rom file.
(If you don't do these changes, you might end up talking to another group's server instead of your own, because there will be several lab groups using the same Sun server. This might cause confusion ...)
Then, change the client's rom file by replacing the number 1234 and 9876 with the same numbers that you have in the server's rom file. Note that the port numbers are ordered differently in the client!
As a final note: It is possible to run x-kernel remotely from home, using ssh, via the machine called remote-und.ida.liu.se (AKA astmatix.ida.liu.se), which means that you can actually do the labs from home. Remember to set the port numbers to something unique when you are logged in remote.

Your first test run of the x-kernel

You are now ready to do the first test run of a protocol in x-kernel. Because your graph.comp file is configured to run the ASP protocol, your xkernel will consequently use this protocol and its corresponding test program, as stored in the asp directory.

Make sure you now have two shell windows opened on your machine. First, in the shell window for the server:

Change over to the server subdirectory in your build directory. Then, type
xkernel -s

This starts a version of the x-kernel on the server. If you get "command not found" then use instead ../xkernel everytime you want to run xkernel (that's two periods and a forward-slash). You will then get something like this in your window:

% xkernel -s
Protocol: ASP
Time: Mon Aug 25 11:06:57 2008
Host: mina11.ida.liu.se
Participant: server

Now, in the other shell window, for the client, change over to the client subdirectory in your build directory. Then, type:
xkernel -c128.1.2.3

This starts a version of the x-kernel on the client. Note that you always have to start the server before the client!

The run of the test program for the ASP protocol involves the client establishing a TCP connection to the server, with a sequence of different-sized messages then sent back and forth between the client and the server. The time it takes to exchange 100 messages of each size between the client and the server will be printed out (see the code in asptest.c for the details). When the run is over, you get something like the below in the window:

Protocol: ASP
Time: Mon Aug 25 11:07:37 2008
Host: mina11.ida.liu.se
Participant: client
Round Trips: 100


Message Length (bytes): 1
Times (sec):
     0.015556
     0.013834
     0.013144


Message Length (bytes): 200
...
...
...
Message Length (bytes): 8192
Times (sec):
     0.060016
     0.057848
     0.057880


Message Length (bytes): 16384
Times (sec):
     0.106677
     0.101206
     0.102376
End of test

This means it took 0.015556 seconds (or 15.6 ms) to send 100, 1-byte messages between the client and server machines (see the first set of messages) and 0.106677 seconds to send 100, 16384-byte messages (the last set of messages).

Note: You can press Ctrl-C whenever you like to stop the protocol.

Other things to try

Now that you are able to build a new xkernel binary in your account, you can start experimenting with different optional configurations. The following gives a list of things you might try. Consult the x-kernel Programmer's Manual for more information on each item.

Add tracing. Edit graph.comp in your build directory by adding the string
trace=TR_MAJOR_EVENTS
to the end of some or all of the following lines
```
name=eth     protocols=simeth;
name=arp     protocols=eth;
name=vnet    protocols=eth,arp;
name=ip      protocols=vnet;
name=icmp    protocols=ip;
name=asp     files=asp/asp 	protocols=ip;
```
For example, the first line would become
name=eth protocols=simeth trace=TR_MAJOR_EVENTS;

Note: there should be a tab before the keyword "trace" in graph.comp. Do similarly with the other lines (protocols in the graph.comp file). Once this editing is done, remember to do a new compilation of xkernel by issuing make again in the build directory.
This change in graph.comp will increase the amount of tracing information that is output when the x-kernel runs. This output will now include events from TCP, IP, ARP, and the Ethernet driver (ETH). To see an even greater level of trace detail, change TR_MAJOR_EVENTS to TR_FUNCTIONAL_TRACE in each of the above lines, and recompile.
Other tips.
In /home/TDTS06/xkernel/protocols you will find the specific code for each protocol TCP, RPC, MSP, etc. that is available to x-kernel. You may find this code useful as a reference when you are thinking up data structures and algorithms for your protocols in labs 1 and 2.

If x-kernel is running as described in the text above, you can now move on to the real work in lab 1.

Page responsible: Andrei Gurtov
Last updated: 2010-09-06