|Overview | Download | Publications | Documentation | Contact|
Tutorial: Running an experiment on SatelliteLab
This tutorial explains how to run a simple experiment on SatelliteLab. In this experiment, we are going to use iperf to measure the available bandwidth on the paths between the of satellites.
Before you start, you will need the following:
The first step is to recruit a sufficient number of satellite nodes. For the purposes of this tutorial, two or three nodes are sufficient (for a 'real' experiment, you will probably need more). There are several ways to recruit contributors; for example, you can ask students, colleagues, friends, or family members. If you just want to try out the software, you could even install the satellite software on a few lab machines.
Point the contributors to the SatelliteLab web site and ask them to install the satellite software on their machines. Also, tell them the IP and port number of the coordinator node (the 'sun'), and ask them to use these settings instead of joining the global testbed. The installation instructions explain where these settings need to be entered during the installation process.
Installing and configuring the coordinator softwareNext, you need to install the coordinator software on the 'sun' node. This software is responsible for pointing the each satellite to the planet node it should associate with. Log into the coordinator node and run the following:
wget http://satellitelab.mpi-sws.org/download/sun-0.9.4.tar.gz tar xvzf sun-0.9.4.tar.gz cd sun-0.9.4 ./configure make
The sun also needs a configuration file. In this tutorial, we will use the simplest possible configuration: there is just a single experiment, and all satellites are allocated to it by default. Please save the following as sun.param:
[general] logFile=sun.log logLevel=4 port=30000 httpPort=8000 webInterface=true adminUsername=admin adminPassword=satellitelab logFlush=true database=dynamic daemon=yes
Here, we're assuming that the port you chose on the sun node is 30000, and that you want to enable the web interface on port 8000. You may want to change these settings, as well as the username and password for the web interface.
Now start the sun software by running:
You should now be able to connect to the sun on port 8000 with your web browser. When you are prompted for a username and password, enter the values you specified in the configuration file. You should now see a list of all satellite nodes that are currently online. It can take up to one minute for the list to be populated, so you may have to reload the web page a few times.
Installing and configuring the planet softwareThe next step is to install the planet proxy, libipaddr, and the software for the experiment (iperf for the purposes of this tutorial) on each of the planet nodes. You can download and compile the software as follows:
mkdir experiment cd experiment wget http://satellitelab.mpi-sws.org/download/planet-0.9.4.tar.gz wget http://downloads.sourceforge.net/iperf/iperf-2.0.4.tar.gz tar xvzf planet-0.9.4.tar.gz cd planet-0.9.4 ./configure make cp planet libipaddr.so .. cd .. tar xvzf iperf-2.0.4.tar.gz cd iperf-2.0.4 ./configure make cp src/iperf .. cd ..Now copy the planet and iperf binaries, as well as libipaddr.so, to each of the planets. Please make sure that the libcrypto library is installed. If you see a floating point exception when you run the binaries on PlanetLab, this is due to a library conflict between your build machine and PlanetLab; please use statically linked binaries in this case.
Setting up the experiment
The next step is to set up the actual experiment. To make the setup easy, we will use the 'autostart' mechanism in the planet proxy, which runs a shell script whenever a satellite registers with a planet. This shell script receives the number of the satellite as a command-line argument, and it can then start the necessary applications. This mechanism is particularly useful when using a random sample of satellites, since we do not know in advance which satellites we will get, and which planets they will register with.Here is the shell script we will use (please save this as run.sh):
#!/bin/bash echo Node $NODEID case $NODEID in 1) LD_PRELOAD=./libipaddr.so NODEID=$NODEID ./iperf -u -s -l 1300 ;; *) sleep 10 for ((i=0; i<3; i++)) ; do let DELAY=20+$RANDOM%40 echo Sleeping for $DELAY seconds sleep $DELAY echo Running iperf LD_PRELOAD=./libipaddr.so NODEID=$NODEID ./iperf -u -c node1.satellitelab \ -t 2 -b 1M -l 1300 done esac
There are two things to note there: First, the script is started with the environment variable NODEID set to the number of the satellite (the first satellite has the number 1). Thus, it is possible to run a different application for each satellite; the script uses this to start iperf in server mode on satellite #1, and in client mode on all other satellites. Second, libipaddr is preloaded before each application. This is necessary to ensure that, when two applications run on the same planet, the traffic they exchange is still routed through the planet proxy, rather than being delivered directly by the kernel. If libipaddr is not loaded as shown above, the experiment can return incorrect results, or may not work at all.
Writing a planet configuration file
The third step is to write a configuration file that tells the planet proxy how to run your experiment. Here is an example configuration file (please save this as planet.param):
[general] enableSun=yes sun=<IP address of the sun node>:<port number on the sun node> allocation=dynamic logFile=planet.log logLevel=4 planetlab=yes startProcessesWhenOnline=yes satelliteCommand=./run.sh pathToLibIpAddr=./libipaddr.so daemon=yes
You may need to change the underlined settings. Under 'experiment', put a unique identifier for your experiment; you will need to enter this identifier later when registering the experiment with the sun. Under 'owner', put the institution identifier that you received with your testbed account. Finally, if you are not using PlanetLab nodes as planets, you need to set 'planetlab' to 'no'.
In this configuration, the proxy is instructed to send status reports to the coordinator node, and to allow that node to dynamically allocate satellites to it. The proxy is also told to start our shell script when a satellite comes online, and to become a daemon after startup.
Starting the planets
Copy the script run.sh and the planet configuration file planet.param to each of the planet nodes. Then start the planet proxy on each of the nodes as follows:
./planet planet.param $HOSTNAMEThe planet proxy should now be running in the background as a daemon process on each machine. There should also be a log file called planet.log on each node. The log may contain some warnings saying that the experiment has not been registered; this is normal at this point.
Associating satellites with planets
Finally, you need to associate each satellite with the nearest planet. Open the web interface and click on the 'default' link under Experiments. This will open another web page that has a button labeled 'Reassociate satellites with planets' at the bottom. Click on this button. The status indicators on all the satellites should now turn yellow and show CFG, which means that the satellites are being configured. If you reload the page a few times over the course of the next 1-2 minutes, you should see them turn green one by one, and the Planet column should show the name of a nearby planet. Finally, the status indicators on the planets should turn green. At this point, the experiment is running.
Collecting the resultsWhen running applications, the planet proxies redirect stdout and stderr to files called satellite<n>.stdout and satellite<n>.stderr, respectively. After the experiment has finished, these files should contain the results from the iperf measurements.