|Overview | Download | Publications | Documentation | Contact|
Tutorial: Using the global testbed
This tutorial explains how to run a simple experiment on the global SatelliteLab testbed. In this experiment, we are going to use iperf to measure the available bandwidth on the paths between a random sample of satellites. If you need access to specific satellites, or if you want to set up your own testbed, please read one of the other tutorials.
Before you start, you will need the following:
Installing the softwareThe first step is to install the planet proxy, libipaddr and iperf 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=galaxy.octarine.de:30000 allocation=dynamic experiment=test owner=mpi-sws logFile=planet.log 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 global testbed, and to allow the testbed to dynamically allocate satellites to it (see the other tutorials for an example with static allocation). 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.
Registering the experiment with the testbed
Next, you need to register the experiment with the testbed, so that satellites can be allocated to it. Enter your username and password here, click on 'Register a new experiment', and then enter the following into the form that appears:
Now click on 'Register'. You should see the testbed status page again, with the new experiment listed at the top.
When using the dynamic satellite configuration, it is very important to ensure that all the planet proxies are running when the sun starts allocating satellites to the experiment. The reason is that each new satellite measures the network distance to each planet and then chooses the 'nearest' planet. If a planet is not online when this happens, the network distance cannot be measured, and some satellites may end up associating with a more distant planet as a result.
Monitoring the experiment
Once registered, the experiment runs automatically; at the specified start time, the testbed will allocate a number of satellites, locate the closest planet proxy for each satellite, and configure proxies and satellites accordingly. The proxies will then start the script file you installed earlier, which in turn runs iperf.
However, you may want to monitor the experiment in case there are any problems. To see the current status, click on the 'Status' link next to the experiment and enter your testbed username and password again. You will see a page that looks approximately like this:
At the top, you see a short summary of your experiment, including the number of planets and satellites. The status of the experiment should initially be 'init'; during this time, the sun waits for status reports from the planet proxies and adds them to the list of planets (if the start time of your experiment is more than one hour in the future, the experiment may not even be listed yet; in this case, please return to this page later). After at most 1-2 minutes, the 'planets' list should contain all the planet proxies you started; if some proxies are not shown, please check the planet.log files on the corresponding nodes.
Once the experiment has started, the 'satellites' list shows all the satellites that have been allocated, as well as the corresponding planets. It is possible that you are allocated fewer satellites than you requested during registration; this usually happens when multiple experiments are running simultaneously and there are not enough satellites for all of them.
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.