Commit 3b61d244 authored by Robert Ricci's avatar Robert Ricci
Browse files

Add some basic documentation for our plab interface. Originally, this

was just supposed to be a list of which problems are ours and which
are theirs, but it kinda grew beyond that.
parent 136d4391
......@@ -38,6 +38,12 @@ PAGEHEADER("Documentation");
asking for help. Includes sections on "Getting Started" on Emulab,
using the testbed, hardware setup, software setup, security issues,
and troubleshooting. Over 50 questions and answers.</dd>
<dt><b><a href="doc/docwrapper.php3?docname=plab.html">
Emulab PlanetLab Interface</a></b></dt>
<dd>Documentation for our interface to PlanetLab.</dd>
Copyright (c) 2003 University of Utah and the Flux Group.
All rights reserved.
<h2>PlanetLab Interface</h2>
<h3>Creating a PlanetLab Slice</h3>
Simply use the 'Create a (PlanetLab) Slice' menu option. Most of the options
have 'footnotes' that explain their use, and things such as our algorithm for
picking nodes. Once you fill out the parameters of your slice, you will be
taken to a page that gives you the opportunity to set things like the name of
the slice and its description. Once you click 'Submit' on the second page, we
will start setting up your slice. When it's ready to use, you'll get email
detailing which nodes you were assigned, etc.
<h3>Using Your PlanetLab Slice</h3>
Once your slice has been created, you can view it by clicking on its name in
the 'Experiment List' link, or from your 'My Testbed/Emulab' page. This page
will let you terminate the slice, or put it into a 'swapped out' state (in
which we keep information about the slice in our database, but it is not
actually instantiated on any nodes). It will also show you which nodes were
allocated to you, and perform operations on these nodes such as rebooting them.
Rebooting a sliver kills off all processes running on it, and re-runs the
Emulab sliver setup code (including your startup command if you supplied one.)
For your convenience, we set up DNS names for all of the nodes in your slice -
each sliver can be addressed like
<code>&lt;node&gt;.&lt;exp&gt;.&lt;proj&gt;</code>, where:
<code>node</code> is the name of the node in your slice (if you used the 'EZ'
form, the names will be 'node-N', starting with 'node-1', up to the number of
nodes in your slice). <code>exp</code> is the name of your experiment (same as
the slice name) and <code>pid</code> is the name of your project on Emulab.
Unlike 'raw' PlanetLab slices, you log into an Emulab-created slice using your
own (Emulab) username. To do this, all of the slivers in your slice run their
own <code>sshd</code>, which must be run on a non-standard port so that it
doesn't conflict with the node's 'main' <code>sshd</code>. The port numbers for
your slice's <code>sshd</code>s are listed in the experiment creation mail. For
interactive use, there are links on the experiment page to <code>ssh</code>
(with a helper application, linked from the column header) using the correct
hostname, correct port number, etc.
<h3>Getting More Advanced</h3>
Our 'EZ' slice creation form allows for simple things like asking for a bunch
of nodes of the same type, or installing the same RPM on all nodes in the
slice. But what if you want to do something more fancy, like ask for 10 nodes
inside North America, and 10 outside? Or run a certain command, on startup, only
on one of your nodes? Well, luckily, there's a lot more power to the
specification interface than what you see on the 'EZ' pages.
What's going on behind the scenes here is that Emulab actually takes as input
an NS file - a very similar file to the one used for the NS network simulator.
The 'EZ' forms are generating an NS file for you, but, of course, you can write
one yourself. On the second page in the slice creation process, you can click
on 'View NS File' to view (and/or save) a copy of the generated NS file. You
can then use this (very commented) file as a starting point for creating your
own, more complicated file. You can then submit this file to the
'Begin/Advanced Experiment' page.
The Emulab documentation covers the parts of NS that are and are not supported,
and Emulab's own extensions to the language.
<h3>Changing Your View of The Web Interface</h3>
We've attempted to make things simple for people who only want to create
PlanetLab slices, by providing a stripped-down version of our web interface. If
you'd like to see the whole interface, use the 'Edit Profile' link on the 'My
Testbed/Emulab' page. There is a checkbox on this page that will allow you to
toggle the interface view you get.
<h3>Where Should I Look for Help?</h3>
When using our interface to PlanetLab, there two different entities responsible
for support: us and the PlanetLab team. Each is responsible for a different
part of the system you are using. So, below are some guidelines on which types
of questions/problems should be addressed to who.
In an emergency, such as being unable to create a slice with a deadline
looming, you can try asking both places at once. However, under normal
circumstances, we suggest trying one at a time.
<h4>Questions that should go to us:</h4>
<li>Any questions or problems relating to our web forms.</li>
<li>Any errors reported in the experiment creation mail you receive.</li>
<li>Questions about any of our 'added' features to PlanetLab, such as
automatic tarball/RPM installation and startup commands.</li>
<li>Questions about getting Emulab accounts or permission to use Emulab's
PlanetLab interface.</li>
<li>Problems with accounts created for you on your PlanetLab slice, such as
being unable to log in or use sudo.</li>
<h4>Questions for which the answer may be on
<a href="">the PlanetLab site</a>,
or should go to
<a href=""></a>:
<li>Questions about the kernels and other software on PlanetLab nodes.</li>
<li>Questions the PlanetLab environment, such as bandwidth limitations and
raw sockets.</li>
<li>Misbehaving nodes, or nodes which are having resource problems such as
full disks, excessive load, or running out of memory.</li>
Supports Markdown
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