Table of contents

• Overview
• Features
• Requirements
• First steps
• Before you can start
• Viewing the node details
• Saving and loading scenarios
• Deploying software to the nodes
• Bootstrapping nodes
• Running an experiment
• History
• License
• Documentation
• Troubleshooting
• Final comments

Overview

Some features are:

Requirements

• The program itself:
  
  • Download PlanetLab Visualizer
    
  • Hosted at SourceForge.net
    
  • Date: 28.08.2009
    
  • Size: ~90 MB
  
  
  
• A PlanetLab account
  
  
• On Linux: ssh-agent (part of OpenSSH) must be running to manage your planetlab ssh-keypair
  On Windows: PuTTY and pageant (included in putty) to manage your planetlab ssh-keypair
  
  
• Java (>= v1.6)
  
  
• Apache ant
  
  
• And an Internet connection ;-)

First steps

Initially you can see the PlanetLab Map window with the world map containing all the PlanetLab sites which offer nodes.
On the left side there are two lists:
The upper one shows all nodes, while the lower one shows only the nodes selected for a scenario.
Most of the operations in the action menu apply to the scenario nodes.

There are two ways to start the program:

1. Using ant:
   
   Just type ant run in the root folder.


2. Otherwise:
   
   Execute ./PlanetLabVisualizer.sh (or PlanetLabVisualizer.bat on Windows) to start the program.
   Make sure that the folder which contains java is in your PATH variable (Windows: look here, Linux: look here).

There are some things you'll need to do before you can start with the tutorial:

1. If you're running the program on a linux platform:

   
   Start the ssh-agent (or pageant) and add your ssh-key to the ssh-agent by using ssh-add /path/to/your/key.

   
   

   On Windows you'll perform this:

   Start the pageant and add your ssh-key to it.
   Make sure that the PuTTY program folder (e.g. C:\Program Files\PuTTY) is in your PATH variable.
   This is needed to execute the pscp.exe when transferring files to nodes.



2. Further your PlanetLab login data (username, password, role and slice name) is needed, enter these in the Preferences dialog of the PlanetLabVisualizer.
   If you're reading this text through the help window, just go to Menu -> File -> Preferences.

1. Viewing the node details:
By clicking on a node on the map or on one of the lists you will get a context menu with the available actions for the node.
Chosing Node Details opens a Window showing more information about a node.

This will open the Node Details window.
Here you can see some node details like it's Hostname, Location, the configured bandwidth-limit of the node
and the Boot-State ("boot" means normal state, other states are: debug (dbg), to be re-installed (rins) and to be first-time installed (ins))


Add the node to your slice by klicking on the "Add to slice" button.
Note that it may take a while until your slice on the new Node is accessible because the ressources need to be allocated first.
Add the node to your scenario configuration by checking "Takes part in scenario"
You may have noticed that the list with the scenario nodes now contains the node:

2. Saving and loading scenarios


• Saving a scenario configuration is easy: Go to File -> Save scenario configuration as.. and select a name for your configuration (i.e. "Tutorial").


• Loading the scenario works similar: Go to File -> Load scenario configuration and chose your configuration name.
  
  
  
  The world map now shows only the nodes which are selected in the scenario.
  (You can change this by selecting View -> "Show all nodes" or "Show selected nodes" from the menu)
  
  
3. Deploying software to the nodes


• Select a node in the scenario nodes list and right click on the entry and chose "Send directory (N)".
  (The (N) means that the operation may be executed for many nodes at once. You can test this by selecting 2 or more nodes in the list and then chosing "Send directory (N)".)
  
  


• Select the deployDir (/.) as the source directory of your local host
  
  
  
  and "~" as the destination directory on the node.
  
  
  
  The deployDir from the PlanetLabVisualizer folder is now transferred to your home directory at the node.
  (On linux the transfer is done using rsync so the next time you need to update your node only the changed files will be copied.
  On Windows systems the whole directory will be transferred using PuTTy as there is no rsync alternative as far as I now.)


• Detailed information of the transfer process is printed to stdout. So you can view these details by switching back to the shell you started the program from.
  
  

There are two alternative ways to transfer files from your PC to the nodes:
1. By opening the node details window and entering the From and To directories in the appropriate fields and then hitting the "Copy directory to node" button
2. It's possible to send the contents of a directory to all scenario nodes. This is specially usefull if you'd like to setup all nodes for an experiment.
   Chose Action -> "Copy dir to selected nodes" to perform this operation.
4. Bootstrapping nodes

The transferred software on the nodes needs to be started to be able to receive commands from the Visualizer e.g. to start/stop an experiment.


• You can bootstrap a node by chosing "Bootstrap" from the node's context menu.
  To bootstrap all scenario nodes chose Action -> "Bootstrap selected nodes" from the menu.
  
  
  There will be a lot of output to stdout while the software is started on the nodes.
  If the bootstrapping process was successful the client software is listening on a remote port for incoming CORBA-RMI connections
  Also a slice-owned ssh-server will be listening on a remote port (only needed for bandwidth-measurements as they are done using scp).


• You can check whether the software on the nodes is running by chosing "Check version" from the node context menu
  or again by chosing Action -> "Get selected nodes versions" from the application menu.
  This is a simple check where a remote method from each node is called. Failed nodes will be marked red in the Node list.
  
  
  
  The details of the operation are again printed to stdout.
  The output may be useful if you want to trace back the reason of the failure (e.g. Connection refused or Connection timed out problems).
5. Running an experiment

As mentioned above, up to now the only implemented experiment is the X2X simulator, which forms groups of the scenario nodes
and then measures the bandwidths between the nodes of each group.

You can open the X2X sim window by chosing File -> Show simulator window.
Here are some screenshots showing the X2X sim in action:


1. Here you can see 2 groups of nodes, each of them consisting of 5 nodes. The groups were formed using semantic closeness.
   The edges shown on the map are drawn from each node to the leader of the group.
   In this scenario the 2 leaders are in Kent (UK) and Göttingen (GER).
   


2. We want to see how thes nodes would form groups if every node (except the leaders) could join the group, to which it has the best bandwidth.
   This means that we're running a Network Closeness experiment by measuring the bandwidths from each node to the leaders to form the Network Closeness based groups.
   Afterwards the average group bandwidth is also calculated again by measuring bandwidths but this time from each node to every other member of the group.
   
   Here you can see the X2X Sim window, where we've selected to execute the Network Closeness scenario (Scenario 2).
   


3. After clicking on the "Execute" button, the Experiment options dialog will be shown.
   Here we can select some options and actions to perform before the bandwidth measurements start.
   


4. Usually the experiment will take a longer time (some hours) but this depends on the number of nodes you selected for the scenario.
   During the execution of the experiment you can watch the current state by taking a look at the stdout.
   


5. Finally when the bandwidth measurements are finished, we can see the newly formed groups:
   
   Note that many of the nodes have switched to the other group.


6. We can now view the results of the measurements to understand the new situation by chosing File -> "Show bandwidth results" and then opening the last measurement results file.
   


For more information about X2X take a look here: http://www-itec.uni-klu.ac.at/~laszlo/x2x.pdf
Well, hopefully my master thesis will be finished soon, so more information should be obtained there ... but time will tell.

History

License

• All of my code stands under the GNU General Public License v2 which can be found in the COPYING file in the root folder of the project.


• The basic parts of the version 1.0 code are copyrighted by the Princeton Board of Trustees.


• The following list shows the external libraries (*.jar) used to realize different features of the PlanetLabVisualizer.
  They are all located in the lib directory.
  
  
  • GeoIPJava
    Owner: Maxmind
    Source: http://www.maxmind.com/app/java
    License: LGPL
    

    Use:

    It's used to find out the locatation (longitude, latitude) of an IP.
    Makes it possible to draw a node on the world map.
    It's used together with the GeoLite City database (GeoLiteCity.dat) which stands under the OPEN DATA LICENSE.
    http://geolite.maxmind.com/download/geoip/database/LICENSE.txt

    Comment: "This product includes GeoLite data created by MaxMind, available from http://maxmind.com"
  
  
  • xmlrpc-client, xmlrpc-common, ws-commons-util
    Owner: Apache Software Foundation
    Source: http://ws.apache.org/xmlrpc
    License: Apache License
    Use: The communication to the PlanetLab-API works using XML-RPC and these libraries are used for it.
  
  
  • jcommon, jfreechart
    Owner: jfree.org
    Source: http://www.jfree.org/jfreechart
    License: LGPL
    Use: They are used to create Bar charts from the bandwidth results.
  
  
  • JacORB
    Source: http://www.jacorb.org
    License: Library GPL
    Use: JacORB is used as the ORB for CORBA interaction between PlanetLabVisualizer and PlanetLabClient. It has replaced the Sun orbd because it provides CORBA over SSL. SSL is important to prevent hijacking of the code running on the PlanetLab nodes. The Client_Keystore (which is in the configs dir) and the Server_Keystore (found in deployDir/PlanetLabClient/configs) should be replaced with your own generated keys to provide security. The file keygeneration.txt (in the configs dir) explains how to do this. However, you'll only need these things if you intend to use the PlanetLabClient to start your experiments on PlanetLab nodes.

Documentation

• This file can be found in the doc folder of the project.


• There is also a text file called README in the root folder of the project. It pretty much contains the same information as it is found here.


• Here you can find the Javadoc API. It may be useful if you are interested in extending the Program.
  If you intend to implement your own experiment logic, you'll need to extend the PlanetLabClient.
  It is a much simpler piece of software than the PlanetLabVisualizer so it should be easier to understand too.
  Most probably you'll need to extend the planetLabVideoClient.idl by inserting your new method prototype and then implementing it in the VideoClientImpl class.
  Note that the PlanetLabClient API is still in development so it's subject to changes that may break your code extensions.
  More detailed information is still to come..


• The original documentation of the PlanetLabVisualizer v1.0 including the Javadoc API can be found here: PlanetLabVisualizer v1.0 documentation

Troubleshooting

• Permission denied errors:
• Don't forget to enter your user-info in the PlanetLabConfig.xml
  (see First steps)
• Don't forget to start your ssh-agent (or pageant) and add your private key to the agent
  (see First steps)


• XMLRPC exception:
If you see something like this:
org.apache.xmlrpc.XmlRpcException: Failed to read servers response: sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Solution: The certificate of the site www.planet-lab.org needs to be updated (it was changed or has expired):
1. You need to get the new certificate from the site e.g. using firefox->View Page Info->Security->View Certificate->Details->export...
2. Then create a truststore file using "keytool -import -alias planetlab -file www.planet-lab.org.crt -keystore truststore"
3. Update the truststorepass - variable in the build.xml file with your new password.
4. Replace the truststore found in the root directory of PlanetLabVisualizer with the new file.

Final comments

I hope this program can help you with your research using PlanetLab. Enjoy it ;-)
For support or if you have any comments, don't hesitate to contact me and give me feedback:

Leo Bosnjak ().

Hosted by