Home | About Gush | Using Gush | Gush Examples | Gush Tutorial at GEC 11 | GENI Summer Camp

---

A Simple Example

Now we will walk through a simple example that shows how Gush works for a trivial experiment on PlanetLab. This example will copy a tarball to 2 PlanetLab hosts, untar it, and then cat the file included. This simple application goes over the basic building blocks needed to manage applications using Gush.

The following files are needed to run this application and are described below. They must be modified slightly (look for machine names and user names) to run on your machines.

1. simple.xml
2. directory.xml
3. gush.prefs
4. software.tar (includes software.txt, which consists of 1 line of text that says "Hello World")

Application Description: simple.xml

simple.xml is a Gush application description file. At the highest level, we define the project, which in this case is called "simple." Next we define any software packages that are needed. Gush application descriptions are comprised of different types of "blocks."

<?xml version="1.0" encoding="utf-8"?>
<gush>
  <project name="simple">
    <software name="SimpleSoftwareName" type="none">
      <package name="Package" type="web">
        <path>http://sysnet.cs.williams.edu/~jeannie/software.tar</path>   //Software tarball
        <dest_path>software.tar</dest_path>
      </package>
    </software>
    <component name="Cluster1">
      <rspec>
        <num_hosts>2</num_hosts>                                           //Number of remote clients
      </rspec>
      <software name="SimpleSoftwareName" />
      <resources>
        <resource type="geni-plc" group="williams_gush"/>
      </resources>
    </component>
    <experiment name="simple">
      <execution>
        <component_block name="cb1">
  	  <component name="Cluster1" />
	  <process_block name="p2">  
  	    <process name="cat">                                        //Define actual execution
	      <path>cat</path>                                          //"cat software.txt"
	      <cmdline>                  
 	        <arg>software.txt</arg>
	      </cmdline>
	      <cwd/>
	    </process>
	  </process_block>
	</component_block>
      </execution>
    </experiment>
  </project>
</gush> 

Environment configuration: directory.xml

directory.xml defines the Gush resource directory. This file tells the Gush default matcher where to locate resources during execution. In the following example, we specify PlanetLab slices available to us, and define a mapping between slice names and port numbers.

<?xml version="1.0" encoding="UTF-8"?>
<gush>
    <resource_manager type="geni-plc">
      <port_map slice="williams_gush" port="61500"/>
    </resource_manager>
</gush>

Gush preferences: gush.prefs

The gush.prefs file defines basic preferences that customize the way applications are run. In this example we specify the ClientPrefix and ClientPath which control how the client is started ({ClientPrefix}/client) and what working directory the client uses when executing commands (chdir {ClientPath}).

<preferences>
  <pref key="ClientPrefix">./</pref>
  <pref key="ClientPath">./</pref>
  <pref key="UsePlanetLab">true</pref>
</preferences>

Start Gush

Now we are ready to run our example. The following shows the output from a run using two clients. You only need to type the commands that appear after "gush>".

$ ./gush -P 15413
gush> Gush has learned about the slice williams_gush.
Updated information on the slice williams_gush is available.

gush> load tests/simple.xml 
Project "simple" is selected.
Experiment "simple" is selected.

gush> run
Starting experiment run.
Running experiment simple...

gush> The configuration matcher has finished matching.
The resource allocator has finished successfully.
williams_gush@planetlab4.williams.edu:61500 has joined the mesh.
The file transfer of Package to planetlab4.williams.edu has been completed.
The software installation of Package on planetlab4.williams.edu was successful.
williams_gush@planetlab5.williams.edu:61500 has joined the mesh.
The file transfer of Package to planetlab5.williams.edu has been completed.
The software installation of Package on planetlab5.williams.edu was successful.
williams_gush@planetlab5.williams.edu:61500,28484: Hello World

williams_gush@planetlab4.williams.edu:61500,25095: Hello World

The experiment has ended.

gush> disconnect
gush> williams_gush@planetlab5.williams.edu:61500 has decided to leave the mesh.
williams_gush@planetlab4.williams.edu:61500 has decided to leave the mesh.

gush> quit