plushy

Using Plush

plushy

Welcome, intrepid users! This page contains information about getting and using Plush. We'll discuss each of those topics in order, starting with instructions on grabbing the current CVS distribution and setting it up. Then you'll be free to peruse links and examples.

Getting Started

Requirements

Plush is written in a mix of C++ and Perl, and we intend for it to be runnable on any UNIX-ish OS. That said, we have been using it primarily with Linux 2.6, FreeBSD, and with Mac OS X.

Plush requires the following libraries:

The ares library (libares) for asynchronous DNS lookups is optional, though recommended for performance on PlanetLab. The boost software package is also required, as well as lex and yacc (we use flex and bison).

Plush uses some Perl helper scripts. If you want Plush to automatically interface with the PlanetLab Central (PLC) database for you, you will need to have Frontier::Client and Crypt::SSLeay properly installed. We'll get to that in the next step.

Getting and building the code

Plush is available via anonymous CVS provided by SourceForge (see the SF Project Summary). Follow the instructions below from a Linux host. NOTE: This statically compiles plush and client. Remove the --with-static compile flags to compile dynamically.

Installing Plush


		  $ cvs -d:pserver:anonymous@plush.cvs.sourceforge.net:/cvsroot/plush login  (press RETURN at prompt)
		  $ cvs -z3 -d:pserver:anonymous@plush.cvs.sourceforge.net:/cvsroot/plush checkout plush
		  $ cd plush
		  $ autoconf
		  $ ./configure --with-static-client --with-static-plush
		  $ make dep
		  $ make

This should create "plush" and "client" binaries in the local directory.

UPDATE: Alternatively, rather than compiling plush yourself, you can try these statically compiled binaries. Just grab the tarball, run helper-scripts/setup.pl (described below), and give it a try. The binaries were compiled on a 32 bit Ubuntu Linux box, but there are no guarantees that they will work correctly for you. You can also try these 64 bit Ubuntu Linux binaries: plush-bin64-ubuntu10.tar.gz.

Checking your host environment

Get an ssh-agent up and running for password-free logins to the hosts listed in your directory, and to PlanetLab hosts. To handle the case where connecting to a new node brings up a fingerprint verification question, add "StrictHostKeyChecking no" to your ~/.ssh/config . Though there are scripts to populate your .ssh/known_hosts file with all the PlanetLab host keys, the keys in the database don't always match the actual keys in use, and relying on those fingerprints will often prevent you from logging into a host.

Plush contains a "Host Directory" component that enumerates the known resources. Any PlanetLab slices and hosts that you have access to should be added to the directory, as should any other hosts that you want Plush to use and have specified. (Remember, you have to have SSH access to these hosts, and you should have set up your local machine with a key pair or some other non-interactive authentication mechanism. We use ssh-agent.) Plush also has the ability to contact the PlanetLab central database to automatically renew your slices, to add or remove hosts assigned to slices, and to query for slice status. Contacting the server requires your planet-lab.org username and your password.

Configuring the directory and PLC password

		
		  $ perl helper-scripts/setup.pl              (Follow the instructions for items 1 and 2.)		  
		

The official warning: Your PlanetLab password is stored in a file called ".passwd" in the plush directory. It is in the clear. Sorry.

To contact the PlanetLab.org database, the perl modules Frontier::Client and Crypt::SSLeay are required. Run a test of the planet-lab script to make sure things are working, replacing "login@cs.williams.edu" with your own PlanetLab email address:

  1. helper-scripts/handle-plcdb.pl login@cs.williams.edu x x listall
  2. If the command above complained about missing modules, either go to CPAN and download the files, or use the cpan utility to do it for you:
    1. su - (or whatever you do to become root)
    2. cpan
    3. install Frontier::Client
    4. install Crypt::SSLeay
    5. quit

NOTE: The handle-plcdb.pl script assumes that you are using PLC. If you want to use PLE instead, modify the URL in handle-plcdb.pl to point to the PLE URL instead the PLC URL.

User Interface

Running Plush

You can now start plush with "./plush". Using the default command-line user interface, Plush tries to act like a shell (well, almost -- unfortunately many of the commands are asynchronous, so you don't have the nice background/foreground distinction present in normal shells). A very-partial list of those commands is listed below; the official source is the "terminal_parser.y" YACC file.

For instant gratification, try the following commands (in red):

    $ ./plush -P 15418 
      Start Plush on port 15418.
      Wait until Plush prints out a message with your slices in it.
    plush> connect pat @planetlab 10 
      Connect to a random set of 10 known hosts that match the substring "planetlab".
      Wait until you see some messages about hosts joining the mesh.
    plush> info mesh
      Print out the current connection status of various hosts.
    plush> shell "ps aux"
      Run "ps aux" on every connected host, and print the results locally.
    plush> disconnect
      Disconnect hosts from the mesh--this kills remote clients.
    plush> quit
    

There are several example application description XML files in the "tests" directory that can be used to experiment with different aspects of Plush. Further, you can go to the Examples page and learn how to run a simple experiment.

Command-line Interface Commands
Plush GUI

There is now a GUI for Plush that allows users to visualize and build their applications without using the command-line interface. Check out the Nebula page for more info.

Screenshots: