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 documentation/">other tutorials.

Before you start, you will need the following:

• A testbed account: Please support/contact.php">contact us to get access. If you have already received your username and password, please testbed/">log in to verify that they work.
• Some planet nodes: You will need root access several machines that are distributed across the same areas as the satellites. For example, you can use nodes from a PlanetLab slice.

Installing the 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=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 documentation/">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 $HOSTNAME

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 testbed/">here, click on 'Register a new experiment', and then enter the following into the form that appears:

• Unique identifier: The same identifier you used in the planet configuration file
• Description: A general description of your experiment (e.g. 'tutorial')
• Start time: The default is fine; your experiment will start at most a few minutes after registration. If you change this value, please remember to use the time zone that the sun is in.
• End time: The default will give you a duration of one hour; you may want to reduce this to get a lower turnaround time in case you want to restart the experiment.
• Planet configuration: Choose 'dynamic'.
• Satellite configuration: Choose 'dynamic' and specify 5 satellites.
• Satellite migration: Choose 'prohibited' (this only matters for long-running experiments).

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 results