People:
Jeannie Albrecht
Ryan Braud
Darren Dao
Alex Snoeren
Amin Vahdat


Tutorials


Prerequisites

This tutorial assumes that you're familiar with PlanetLab, and that you have already created and set up your SSH key. You should be able to SSH into PlanetLab hosts from the machine from which you plan to run Plush/Nebula. Please refer to the PlanetLab User's Guide for more information.

Furthermore, you need to be able to SSH into the hosts without having to enter the passphrase. To allow that, you need to have ssh-agent running and you need to add your identities to the agent by using the following command:


Installation

Please refer to the installation page.

Configuration

1. Refer to the Plush User's Guide for how to configure Plush.
2. To configure Nebula, first start it by running the following command from the root nebula directory:
 
3. Go to Edit -> Preferences -> Plush, and fill in the location of Plush under "Plush Location". For example, mine is set as follows:

Note: you cannot use ~ in this path.

4. [Optional] You can also change the default value for "Plush port" and "XML-RPC callback server URL" if you want, although the defaults should be fine.

Beginner tutorial: Monitoring PlanetLab hosts

1. Start Nebula.
2. By default, you will be presented with the "World View" of PlanetLab.



3. Go to Plush -> Start Plush.
4. Once Plush starts and has retrieved the necessary data from PlanetLab Central, the "World View" map will be populated with PlanetLab sites.
5. You can zoom in and out of the map by using the mouse scroll wheel.
6. You can also zoom into a specific portion of the map by holding down the left mouse button and dragging it over the portion of the map you want to zoom in on.
7. To scroll around the map, hold down the right mouse button and drag the mouse.
8. To monitor PlanetLab hosts, Nebula provides a graphical indication of the hosts' status. The following metrics are supported:

9. To monitor a specific site, simply double-click on the site. This will bring up a popup window like the one below:

   
This window shows the status of all the hosts in the site and also includes a graph that displays the statistics of the hosts based on the chosen metric. If you want to monitor a particular host, open up a zoom window (Step 6) and double-click on a particular host.
10. If you want to monitor a particular metric across all sites at once, go to Plush -> View Load Metric, and choose any metric that you like. This will cause the slices to start changing color. The color ranges from green to red, with green corresponding to low values and red corresponding to high values.

 

Beginner tutorial: Viewing hosts in your slice

There are two ways to view PlanetLab hosts:
1. Display all PlanetLab hosts (this is the default).
2. Display only hosts that are in your slice (specified in Edit -> Preferences -> Plush).
You can toggle between the two modes by selecting Plush -> View Slice Hosts.

Beginner tutorial: Adding hosts to your slice

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Once Plush has finished getting data from PlanetLab Central, go to Plush -> Add Hosts to Slice. As mentioned in the Viewing hosts in your slice tutorial, Nebula displays all of the PlanetLab hosts by default. If you are in "View Slice Hosts" mode, Nebula will now display all the hosts.
4. Drag a selection window over sites you would like to add to your slice.
5. A window will pop up with all hosts in the sites you highlighted.
6. Deselect any hosts you do not wish to add to your slice by clicking on the check box next to their name.


7. Click OK to finish, or Cancel to not add any new hosts.
8. Repeat steps 4-7 until you have added as many hosts as you like.
9. Toggle Plush -> Add Hosts to Slice.  

Beginner tutorial: SSH'ing into PlanetLab hosts

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Go to Edit -> Preferences -> SSH and type in the appropriate input for the "Private key location" field. This should be the private key you use to log in to PlanetLab machines.


4. Click OK to save the changes.
5. Switch to the "Host View" tab. This tab will display all the hosts that are assigned to your slice.
6. Select the host that you want to SSH into. Right click on the selected host. A menu will pop up, giving you the option to SSH into the host.


7. Once you select "SSH to <host>", a new tab is added to Nebula. This tab contains an SSH terminal to the host you selected.

Beginner tutorial: Creating and running a simple "Hello World" application


The goal of this tutorial is to help you create and run a simple Plush application that will create a "HelloWorld.txt" file on 2 different PlanetLab hosts.

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Switch over to to the "Application View" tab. This view is used for creating Plush application specifications and running them.
4. Click on the "Component" button to create a Component Block. A Component Block is an abstract container where you can specify the resources for your Plush application. In this tutorial, we want to create a Component Block that has 2 PlanetLab hosts.
5. In the "Add Component Block" dialog box, fill in the appropriate fields as follows, and then hit OK. Make sure to enter the slice you wish to use.



6. The newly created Component Block will be displayed on the panel. Select it by clicking on it, and then click the "Process" button to add a process.
7. To edit the newly created process, double-click on it. This will bring up the "Edit Process" dialog. Fill in the text fields as follows, and then hit OK.


This will tell the Plush Application to run the touch "HelloWorld.txt" command on the PlanetLab hosts.

8. At this point, you should have a Plush Application that looks like this:


9. Save the Plush Application by going to File -> Save As, or simply by pressing Ctrl + S.
10. You are now ready to run the application. To do so, simply click on the "Run Application" button.

Intermediate tutorial: Using SWORD queries


The goal of this tutorial is to familiarize yourself with the integrated SWORD support that Nebula/Plush provides. SWORD is a resource discovery tool for PlanetLab. It lets you query for hosts that match your requirements. To read more about SWORD, go here. To see some sample of SWORD queries, please visit the FAQ section.

For example, suppose you want to deploy your application on hosts that have good response time. Here is what you do:

1. Create a Component Block. In the "Add Component Block" dialog box, click the "More>>" button. This will bring up the "Advanced Settings" dialog, which allows you to specify your SWORD query.
2. For the "Attribute" drop-down menu, select "resptime". Then fill out the rest of the text fields as follows:


3. The inputs specified above tell Plush to only pick hosts that have an ideal max response time of 2 seconds, and an absolute max response time of 3 seconds. Here are more information on what each of the text fields mean:

4. Click the "Add/Update" button. This will add the SWORD query to your Plush application specification.
5. Click "OK" to finish.

Intermediate tutorial: Running commands on your PlanetLab hosts

Nebula provides a user-friendly interface for running commands on arbitrary subsets of PlanetLab hosts in a user's slice. This functionality is provided in the "Host View" tab.

Suppose you want to quickly check what processes are running on some of your PlanetLab hosts (by running the "ps" command). Here is what you can do:

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Switch over to the "Host View" tab. This tab displays all of the PlanetLab hosts that belong in your slice.
4. Highlight the hosts that you want to run the command on.
5. In the text field next to the "Run Command" button, type in the command "ps".
6. Click on the "Run Command" button to execute the command.
7. The values under the "Status" colum will change accordingly.
8. The outputs are displayed inside the Output area.



Advanced tutorial: Using predecessors


The goal of this tutorial is to introduce the concept of predecessors. With predecessors, you can specify the flow of control in your application specification. Specifically, you can specify the order in which your processes should be run.

For example, suppose you want to download the homepage of Google and Yahoo, and then tar up the result. Here is what you need to do:

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Switch to the "Application View" tab.
4. Create a Component Block that has 1 host.
5. Select the Component Block and insert a process by clicking on the "Process" button.
6. Double-click on the newly created process, and edit it as follows:

This tells Plush to run wget to download Google's homepage and save the result to a file called "google.html".

7. Create another process to download Yahoo's homepage and save it into a file called "yahoo.html".

8. Now, we want to tar up the result. So create a third process and edit it with the following values:

9. At this time, what we need to do is to specify that the first two processes must finish running before the third one can begin (otherwise, we won't have anything to tar up). This can be done by assigning predecessors:
    a. First select process 1. Then hold CTRL and click on process 3. This will make the first process becomes the predecessor of the third one.
    b. Do the same thing between process 2 and process 3. At the end, you should have a component block that looks like this:


10. Save the Plush Application and then run it.

Advanced tutorial: Using software and barrier components


The goal of this tutorial is to introduce the concept of barriers, which allows you to synchronize various phases of execution within your distributed application.

To understand how to use barriers, consider the following scenario. Suppose we want to deploy a simple file distribution application. This application consists of two groups of machines. One group is the server machines that store the files, and the second group is the receiving machines that need to get the files from the servers. The goal of the application is to experiment with the use of an overlay network to send files from the source to the receiving clients using some new file distribution protocol. In this example, all senders and receivers must join the overlay before any transfers begin. Also, the servers must prepare the files for transfer before the receivers can start.

Here is what we need to do:

1. Start Nebula.
2. Go to Plush -> Start Plush.
3. Switch to the "Application View" tab.
1. Click on the "Software" button to create a software component.
2. Double-click on the newly created software object. This will bring up the "Edit Software" dialog.
3. In the "Edit Software" dialog, specify the following values:

This tells Plush that it can download the server application from "http://yourwebsite.com/server.tar" and save it as server.tar.

4. Create another software component for the client application. Set it to have the following values:

5. Click on the "Component" button to create a component block for the server. In the "Add Component Block" dialog, specify the following values:

6. Create another component block for the client with the following values:

7. Create the appropriate processeses and barrier as follows:


Note: Notice that the name of the barrier (in blue) is the same for both component blocks. This is to synchronize the processes between the server and the client. It makes sure that the server has set up the files and joins the overlay network and that the client has joined the overlay network as well, before starting the sending and receiving processes. Also, we assume "prepare_files.pl" and "send_files.pl" were present in "server.tar", "receive_files.pl" was included in "client.tar", and "join_overlay.pl" was included in both.