Image: ESA - C.Carreau (SEMPDN9OY2F)
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:

  • A testbed account: Please contact us to get access. If you have already received your username and password, please 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

The 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 $HOSTNAME
The 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:

  • 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:

Experiments

IdentifierStatusStartTime leftPlanetsSatellites
testINITThu Jun 12 13:00:00 2008 59:033/33/3 (+2)

Planets

AddressPortStatus
planetlab01.mpi-sws.org30000OK
planetlab01.cs.washington.edu30000OK
ricepl-1.cs.rice.edu30000OK

Satellites

IdentifierStatusDomainPlanet
AA FA 5D 63 B5 B3 A5 0FOKmpg.deplanetlab01.mpi-sws.org:30000
AA 64 6F EE 92 97 7E 31OKmpg.deplanetlab01.mpi-sws.org:30000
AA 4D B0 99 47 0E FD FDOKrice.eduricepl-1.cs.rice.edu:30000
AA BA AD B4 1B 48 62 CCOKmpg.deplanetlab01.mpi-sws.org:30000
AA E7 21 E3 C3 C0 25 E2OKmpg.deplanetlab01.mpi-sws.org:30000
AA DB 9F 41 1F 8C 8B B7OKwashington.eduplanetlab01.cs.washington.edu:30000
AA 61 9B AD B1 9F BF 17OKmpg.deplanetlab01.mpi-sws.org:30000

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

When 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.

© 2017 The Max Planck Institute for Software Systems
Imprint | Data Protection