Commit 9ab6dd21 authored by Robert Ricci's avatar Robert Ricci
Browse files

Updated the README to take into account changes that have been made

since it was written.
parent a20fd455
----------------------------------------------------------------------
Flexlab software release - Beta
----------------------------------------------------------------------
Disclaimer:
This software is currently in beta. It still needs a lot of polishing, and is
somewhat brittle in the face of PlanetLab node failure, which is frequent.
----------------------------------------------------------------------
Basic information:
We suggest that you read the paper "The Flexlab Approach to Realistic
Evaluation of Networked Systems", by Ricci, Duerig, et al. in the proc. of NSDI
2007 for an explanation of how Flexlab works.
You might see references to 'pelab' (PlanetLab + Emulab) in this software -
this was the internal name for this project, and not all references to it have
been purged.
----------------------------------------------------------------------
What is supported:
* Automatic creation of an experiment of any number of nodes
......@@ -5,103 +24,136 @@ What is supported:
* Running experiments on the real PlanetLab or a 'fake' PlanetLab inside
of Emulab - or both in the same experiment
* Automatic tcpdumps of emulab-side traffic
* Automatic software installation, and running and instrumenting server
code
* Automatic tcpdumps of your traffic on the Emulab and PlanetLab side
* Automatic logfile gathering
* Automatic collection of log files at the end of an experiment
* Easy starting/restarting of stubs and monitors
* Asking for specific PlanetLab nodes or sites
* Setting initial conditions for nodes based on flexmon data
----------------------------------------------------------------------
What is not supported:
* Automatic tcpdump on the real PlanetLab (planned)
* Running test clients (ie. 'iperf -c') for you (planned)
* Asking for specific planetlab nodes (planned)
* Specifying point to point traffic shaping for the Elab initial conditions
and for fake planetlabs. This should be taken care of by whatever
mechanisms are used to fetch wanetmon data
* Instrumenting programs that use preemptive (ie. kernel-level) threads
(planned)
----------------------------------------------------------------------
Running an experiment with the auto-pelab scripts:
1) Create a tarball of the version of the pelab software (monitor, stub, etc.)
that you'd like to test:
Go to your testbed source tree
Run 'cvs up'!!!
Run 'gmake' in pelab/stub, pelab/magent, pelab/libnetmon and pelab/iperfd
(on a DevBox machine)
From the root of your source tree, run:
tar czvf /proj/tbres/my-pelab.tar.gz pelab
Note: Depending in how you got the source, it will either be in a directory
called 'flexlab' made by untarring the tarball, or in the 'pelab' subdirectory
of the testbed CVS repository.
1) Build the flexlab software:
Swap in an experiment using the 'PLAB-DEVBOX' image. Note that this disk
image corresponds to PlanetLab v4.0, and that binaries built on it
will not run on v3.3 nodes, due to incompatible system libraries. Note
that if you already have a Flexlab experiment swapped in, you can use
the nodes in the Emulab side of it for this purpose.
Run 'make' in the root directory of the Flexlab source
2) Create a tarball of the version of the Flexlab software (monitor, agent,
etc.) that you'd like to test:
From the root of your Flexlab source tree, run:
sh ./make-tarball /proj/<PID>/my-pelab.tar.gz
Of course, don't name it 'my-plab.tar.gz'! You can put this file in
a subdirectory if you want, but it must be somewhere in
/proj/tbres/
Or you can use the pelab/make-tarball script to create the tarball:
cd pelab; ./make-tarball /proj/tbres/my-pelab.tar.gz
It is a little more selective about what goes in the tarball.
/proj/<PID>/, where <PID> is the project ID of the project you're
going to run the experiment in (for example, 'tbres')
Put the path to your tarball in the pelab_tar variable in auto-pelab.ns
2) Read the user-settable options at the top of auto-pelab.ns and change them
to your preferences.
3) Use auto-pelab.ns to create an experiment
3) Use your modified auto-pelab.ns to create an experiment and swap it in
4) Once it has swapped in, and you're ready to start an experiment, run the
'start-experiment' script on ops. It will
Restart monitors and stubs
'start-experiment' script from your source directory on ops. It takes as
arguments the pid and eid of your experiment. It will:
Restart monitors and agents
Reset ALL link shaping to the defaults from the NS file
Set initial conditions for all paths from the flexmon database
Clean logfiles
Restart iperf servers on all 'elab-*' nodes
Restart the user-specified servers on all 'elab-*' nodes
start-experiment has a few useful options for passing additional
arguments to the stubs and monitors, e.g.
start-experiment -s '-d' pid eid
would turn on debugging in the stubs
arguments to the agents and monitors, e.g.
start-experiment -s '-d' pid eid
would turn on debugging in the magents
start-experiment -m '-d' pid eid
would do the same for the monitors (assuming it has a '-d' option).
If you are monitoring real planetlab nodes instead of the emulated
nodes, run start-experiment with '-p'.
Important: If you are using real planetlab nodes, instead of a 'fake'
planetlab inside of Emulab, run start-experiment with '-p'.
Important: If you want to have the initial conditions for your paths set
to measured values, rather than 0ms 100Mbps (and you should...), give
start-experiment the '-i' flag
4a) If you modified something in the pelab (e.g., the stub) and need to
Important: Watch for errors from start-experiment - errors about 'no such
file or directory' when cleaning out logfiles are harmless, but other
errors can be important.
4a) If you modify something in the flexlab (e.g., the agent) and need to
deploy it to the nodes, first recreate the tarball as in step 1,
and then
install-tarball pid eid
this triggers a program agent on all the nodes telling it to update
the tarballs and RPMs. You will need to run start-experiment again
after this to restart stubs/monitors.
after this to restart agents/monitors.
5) Log into the 'elab-*' node or nodes, and run your experiment (ie. one run
of iperf). Make sure to run them with 'instrument.sh'.
of iperf). Any programs that you run should be prefixed with
'/local/pelab/monitor/instrument.sh'. This shell script sets up environment
variables so that your program has all of its network calls instrumented.
All command line arguments are passed through to the program - ie:
/local/pelab/monitor/instrument.sh iperf -c elab-2
6) When your're done with your experiment, run 'stop-experiment' on ops. It
6) When you're done with your experiment, run 'stop-experiment' on ops. It
will:
Stop the stubs, monitors, and iperf servers
Collect logfiles from all of the nodes in the experiment, including
stub/monitor logs, tcpdumps, delay agent logs, and so on
Run tcptrace on all tcpdump logs to produce xplot graphs
Put all of these things in a zip file for you in the experiment's log
directory (/proj/PID/exp/EID/logs)
directory - you will get a message like 'Created log hole archive:
EXP.5.zip. This file can be found in (/proj/PID/exp/EID/logs). A new
zipfile is kept for each experiment, and old ones are not automatically
deleted.
7) If you want to look at the logs, unzip the .zip file somewhere, and see
the description of the files it contains below
the description of the files it contains below. If you want to look at logs
as the experiment runs, they are typically in /local/logs/ on the nodes.
----------------------------------------------------------------------
Important places:
* Logfiles from the monitors, stubs, etc. can all be found in /local/logs
on the node while the experiment runs. You can tail the .out or .err
files to see the stdout and stderr of these processes
* The contents of the flexlab tarball are installed in /local/pelab on each
node
* Logfiles from the monitors, agents, and the user-specified server program
can all be found in /local/logs on the node while the experiment runs. You
can tail the .out or .err files to see the stdout and stderr of these
processes
* Inside the archive zip file you will find:
elab-*/ - Logifles from the emulator hosts (more detail below)
even-sched.log - Log of all events (including dummynet control events) sent
elab-*/ - Logifles from the emulator hosts
event-sched.log - Log of all events (including dummynet control events) sent
during the experiment
plab-*/ - Logfiles from the FAKE plabnetlab nodes
planet-*/ - Logifles from the REAL planetlab nodes
tbsdelay*/ - Logs from the delay nodes, including tcpdump traces
planet-*/ - Logifles from the REAL PlanetLab nodes, including tcpdump traces
of traffic to and from the PlanetLab nodes
tbsdelay*/ - Logs from the delay nodes, including tcpdump traces from the
emulab nodes
Node
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment