Simplifying your PlanetLab experience with PlMan
Contents
· Usage
§ Selecting nodes to connect to
Prerequisites
This tutorial assumes that you successfully can log in to a PlanetLab node using ssh from your local machine. For instructions of how to do this, please see the PlanetLab User's Guide.
If you completed the above guide, use this command to test that you have a working private key.
ssh -v -l MY_slice -i /home/username/.ssh/id_rsa planetlabhost
MY_slice is the slice you were assigned by the PI at your site
/home/username/.ssh/id_rsa is the location of your private key
planetlabhost is the hostname of a planetlab node in your slice
Installation
· PlMan is written in Java and requires Java version 1.5 or higher, if you are uncertain of your Java version download the latest Java JRE from the Java homepage.
· Download PlMan from the PlanetLab Experiment Manager homepage. There are separate packages for Windows, Linux and Mac
· Unpack the package
Configuration
In your PlMan folder, edit the file pl_manager.conf
Change at least the following fields:
· Specify Username to be the username you use to log in to the PlanetLab homepage. This is of the format user@institution.edu
· Specify Slice to be the slice name assigned by the PI at your site, for example uw_ls
· Specify PrivateKeyFile to be the path where the private key you use for PlanetLab is located, for example /home/MY_USERNAME/.ssh/id_rsa
NOTE to windows users: the path must be specified with double back-slashes “\\”, for example “z:\\ssh\\identity”
You can also specify values for AuthString (the password you use to log in to the PlanetLab homepage, and PrivateKeyPassword (the password associated with your private key). It is recommended to leave these as is, resulting in you getting prompted to supply them every time you start PlMan.
Usage
First
Connection
To run PlMan, locate the folder to which you unpacked the installation package.
· On Windows, navigate to your PlMan folder and double click the run_win_x86.bat file, a command window will pop up.
· On Mac, open a shell in your PlMan folder and type ./run_mac.sh
· On linux, open a shell in your PlMan folder and type ./run_linux_x86.sh
The command window will now ask you to type in your passwords for the PlanetLab homepage (“AuthString”) and for your private key. Once these are supplied the application will contact PlanetLab Central to get a list of hosts in your slice, as well as start the graphical user interface.
You are now presented to the initial PlMan screen. From the connect menu, select “select hosts wizard”
The “Select host wizard” will now present you with a table with information about the hosts in your slice. Here you can select the hosts you want to connect to, or num random hosts or one host in num random sites.
When you press finish PlMan will connect to the selected hosts.
To execute a command in parallel on all connected hosts, type the command in the command field and click the “execute” button
Done
Adding
nodes to your slice
To add nodes to your slice, select “Add hosts to slice” from the “PLC” menu.
The table will show all hosts that are not yet in your slice, as well as data collected by CoMon for the hosts. If CoMon information is unavailable, a question mark is displayed. This usually means that the host is down.
To add hosts to your slice, simply select the ones you want, either manually or with the quick select buttons. When you press finish, the hosts will be added to your slice. Remember that it can take up to 24 hours before changes are propagated from PlanetLab Central to the PlanetLab hosts.
Select
hosts to connect to
PlMan offers multiple ways to select which hosts to connect to.
Quick Connect
Quick connect is the simplest, just type in an IP-address or hostname, and PlMan will connect to that host.
Connect to hosts in
a file
This is useful if you already have selected a set of hosts, and want to connect to them again. Connected hosts can be saved by choosing “Save connected hosts to file” from the connect menu. This will give you a file with the hosts that are currently connected. Once you have this file you can connect to the same hosts again by choosing “connect to hosts in file” from the connect menu. The file format is just a normal text file with one hostname per line.
Connect using the
Select Host Wizard
You can also choose which hosts to connect to using the Select Host Wizard. You access the wizard from the connect menu. Here you will be presented with a table of hostnames and data, for example load average and free memory collected by CoMon. The select host wizard also allows you to select hosts randomly, or even select a number of random sites, and in each site select a random host.
Uploading your experiment
PlMan
allows you to reliably upload your files to the hosts you are connected to.
There are to ways to do this, either by uploading one file at the time by
selecting “Upload File” from the “Transfer” menu, or by recursively uploading
one directory by selecting “Upload Directory”, this will also recursively
upload any subdirectories in the selected directory.
When
uploading four steps are performed:
1. The md5 checksum of the local
file(s) is/are calculated
2. The md5 checksum of the
remote file(s), if existing, is/are calculated
3. A file is uploaded if
a. The file is missing at the
destination
b. The file exists, but has a
different md5 checksum at the destination
4. After completed transfer, the
md5 checksum of the remote file is calculated to verify that the transfer was
successful.
If
one file is uploaded, it will be uploaded to the slice home directory on each
connected PlanetLab node.
When
a directory is uploaded, a new directory with the same name as local directory
is created in the slice home directory on each connected PlanetLab node, and
the directory contents is uploaded to that directory.
Downloading the results
PlMan
also allows reliable downloading of files. This is done using the “Download
Wizard” accessible from the “Transfer” menu.
“Local
target directory” is the local directory to which the selected file or
directory is downloaded.
“Remote
directory or file” is the remote directory or file to download
“filter”
is a filer for which filenames to download using standard grep pattern matching
on the entire remote path
“naming
convention” specifies how files will get named locally
·
“Flat”
means that all downloaded files will be copied to the same local folder. The
following naming scheme is used: Suppose you download “/tmp/output.log” from neu1.6planetlab.edu.cn
the local file will become
local_directory\neu1.6planetlab.edu.cn_tmp_output.log on windows and
local_directory/neu1.6planetlab.edu.cn_tmp_output.log on mac and linux.
·
Hierarchical
means that all downloaded files will be created in a hierarchical manner in the
local folder. Suppose you download “/tmp/output.log” from
neu1.6planetlab.edu.cn the local file will become
local_directory\neu1.6planetlab.edu.cn\tmp\output.log on windows and
local_directory/neu1.6planetlab.edu.cn/tmp/output.log on mac and linux.
Scripting your
experiment
PlMan offers a rich XML-RPC interface that can be used by advanced users for scripted operation. This makes it possible to control your experiment using any language that supports XML-RPC. We have tested both Python and Perl successfully. The full documentation for scripted operation is available in the PlMan XML-RPC documentation. An advanced example written in Perl is available for download here.