OceanStore The OceanStore Project
HOWTO run Pond, the OceanStore prototype

This page contains information to help you configure and run OceanStore using the tools in the run directory. I've probably left out something very important; email me if you have any trouble.

Using run-experiment
The main script used to start up OceanStore nodes is run-experiment, found in the run directory. Most of our benchmark scripts rely on run-experiment, so the information on this page applies more or less directly to them as well. This script takes an
experiment file as input. That file describes what sort of OceanStore nodes to create and where to run them; we'll describe that file below.

run-experiment can configure and run hundreds of virtual OceanStore nodes on dozens of remote machines. It coordinates sharing information across config files, pushing data to remote sites, monitoring remote processes, and cleaning up all sites afterward.

Most of the real work is handled by a shared Perl module, Tools.pm. This library is somewhat efficient and rather sophisticated Perl, so please ask me before making changes to it yourself.

You usually must set a few environment variables before calling run-experiment:

There are several other useful variables you might want to try:

Experiment File
The files cluttering up the run directory that end in .exp are all experiment files. There are four main sections to an experiment file. Each is described below. Any text on a line following a '#' character is considered a comment, and is ignored.
  1. Host specification
    The first line of the experiment file lists the hosts on which to run the OceanStore nodes. It may be omitted. You can use hostnames, IP addresses, or the keyword "ENV", which tells run-experiment to use the contents of the OSTORE_SERVERS environment variable.
    Format: hosts < host list >
    Default: hosts ENV
    Example: hosts localhost
    Example: hosts x2 localhost foo.cs.berkeley.edu
  2. Topology specification
    Specify a topology file if you want the OceanStore network layer to emulate an artificial topology. This line may be omitted. The keyword "NONE" disables this feature. You may use the variable
  3. Virtual machine specification
    The meat of the experiment file--these lines describe the OceanStore nodes that run-experiment will run. ${graph_dir} in the filename. It generally evaluates to run/graphs.
    Format: < tag > < config > < tapestry mode > < exit type > [ host index [ topology index ] ]

    The following example starts up the first inner ring machine on the 3rd (index 2) host, and does not specify a topology index. Example: Ring0 ${run_dir}/inner.cfg static daemon 2

  4. Parameter definitions
    You can override configuration parameters on a per-experiment basis. The parameters are set before interpolating the template variables, so you can insert a literal value or a variable name.
    Format: set < tag.stage.parameter > < value >
    Example: set Ring*.Inner.block_size 256
    Example: set Client-23.DTree.nodes_to_avoid ${Ring3ID}

Node Configuration File
Each OceanStore node needs a SandStorm configuration file. We use template files that allow us to fill in (interpolate) useful variables at run-time. These variables make it easy to share templates across similar nodes, share information among nodes that are supposed to communicate (e.g. the RP and client nodes), move experiments easily among environments (e.g. from localhost to the cluster to planetlab).

The format is pretty simple XML, but we don't have a DTD written up. Each file includes a header with global information, like thread management, queue thresholds, and local node ID. The rest of the file is a list of stage entries. Each names a stage, the Java class file to run for that stage, and possibly some initialization parameters.

Most configuration templates are copied from an existing file and modified slightly. To minimize the horrible damage caused by copy and paste, I've implemented hierarchical components for configuration file. The new generation of configuration files are mostly a list of other files to include; these included files describe commonly used stages, and are shared by several SandStorm configs. Take a look at run/*inner*cfg to see what I mean.

It is not required that you use the new style. You can still inline all your header and stage definitions if you wish; however, I will refuse to help you if you have problems and I think they might be caused by slightly-inconsistent stage parameters. We already have enough copy-and-paste in our code. It's been hurting our configuration as well.

Variable Interpolation
There are a large number of variables you can use when writing configuration templates. Just put ${Variable} where you want the value of < Variable >. The braces are required.

Most variables are already in use somewhere, and you can learn their use by example. I'll give a short list here; it will probably be out of date by the time you read this, though. Look at examples, and ask me if you think we need to add something.

Other Tools
There are a few other scripts in run that help working on remote machines. They are particularly useful for running experiments on planetlab.
SourceForge Logo
Last modified on Sat Jan 11 17:31:53 PST 2003 by geels.