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:

• Some planet nodes: You will need root access to a few (at least two) machines that are distributed across the same areas as the satellites. For example, you can use nodes from a PlanetLab slice.
• A coordinator node: This can be any machine, as long as it has a static IP address and is not behind a NAT or a firewall. Since the coordinator keeps the satellites and planets together, we sometimes call it the 'sun'. You also need to pick a free UDP port on the sun. In this tutorial, we will use port 30000, but any other port is fine as well.

Recruiting satellites

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 software

   
   tar xvzf 
   cd 
   ./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:

   ./sun sun.param

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 software

   mkdir experiment
   cd experiment
   
   wget http://downloads.sourceforge.net/iperf/iperf-2.0.4.tar.gz
   tar xvzf 
   cd 
   ./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 ..

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.

   #!/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 $HOSTNAME

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 results