A Simple Example

Now we will walk through a simple example that shows how Plush works in a variety of different settings. This example will copy a tarball to 2 local clients, untar it, and then cat the file included. This simple application goes over the basic building blocks needed to manage applications using Plush. We will also go over how to run the same application on PlanetLab with a simple modification to the application description.

Looking for Modelnet? You can find a Modelnet example here.

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

  1. simple.xml
  2. directory.xml (this can be created using helper-scripts/
  3. plush.prefs (this can also be created using helper-scripts/
  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 Plush 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. Plush application descriptions are comprised of different types of "blocks."

      <?xml version="1.0" encoding="utf-8"?>
	<project name="simple">
	  <software name="SimpleSoftwareName" type="none">
	    <package name="Package" type="web">
	      <path></path>   //Software tarball
	  <component name="Cluster1">
	      <num_hosts>2</num_hosts>                                       //Number of remote clients
	    <software name="SimpleSoftwareName" />
		<resource type="ssh" group="local"/>                         //Which hosts do we want to use?
	  <experiment name="simple">
	      <component_block name="cb1">
		<component name="Cluster1" />
		  <process_block name="p2">
		    <process name="cat">                                      //Define actual execution
		      <path>cat</path>                                        //"cat software.txt"

Environment configuration: directory.xml

directory.xml defines the Plush resource directory. This file tells the Plush default matcher where to locate resources during execution. In the following example, we define several different types of resources. We specify PlanetLab slices available to us, and define a mapping between slice names and port numbers. Then we define two "local" resources running on different ports on Plush can run multiple clients on the same machine using different ports, or it can run across several different machines.

      <?xml version="1.0" encoding="utf-8"?>
        <resource_manager type="planetlab">
          <user></user>                                     //PLC login
          <port_map slice="ucsd_plush" port="15415"/>                            //Available slices + default port
          <port_map slice="ucsd_plush2" port="15416"/>
        <resource_manager type="ssh">
          <node hostname="" user="albrecht" group="local"/>
          <node hostname="" user="albrecht" group="local"/>

Plush preferences: plush.prefs

The plush.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}).

       <pref key="ClientPrefix">.//</pref>
       <pref key="ClientPath">./</pref>

Start Plush

Now we are ready to run our example. The following shows the output from a run using two local clients. You only need to type the commands found in red.

    $ ./plush -d 5 -P 15413
    Plush has learned about the slice ucsd_plush.
    Plush has learned about the slice ucsd_plush2.
    plush> load simple.xml
    simple is selected.
    simple is selected.
    plush> run
    Starting experiment run.
    Running experiment simple...
    plush> The configuration matcher has finished matching.
    The resource allocator has finished successfully. has joined the mesh. has joined the mesh.
    A file transfer request for Package has been completed.
    A software installation request for Package was successful.
    A file transfer request for Package has been completed.
    A software installation request for Package was successful.,14209: Hello World,14210: Hello World
    The experiment has ended.
    plush> disconnect
    plush> has decided to leave the mesh. has decided to leave the mesh.

    plush> quit

Running on PlanetLab

To run the same application on PlanetLab, you only have to change one line in simple.xml (assuming you have run and have created the .passwd file necessary for accessing PlanetLab resources as described here). The only line that must be changed is the line that specifies the resource type and group. This tells the Plush default matcher to use resources assigned to the ucsd_plush slice instead of the resources in the "local" group. Now you can run the application in the exact same way (see "Start Plush" section above).

      <component name="Cluster1">
	 <software name="SimpleSoftwareName" />
           <resource type="planetlab" group="ucsd_plush"/>