README

Welcome to Emulab!

This is the "official" source code for the software that runs the Emulab
network testbed at the University of Utah, as well as dozens of testbeds at
other sites around the world.

    http://www.emulab.net/

This is a snapshot of a rapidly evolving system.  It contains all Emulab
source required to build a running testbed, but interaction with Emulab
admins at Utah and elsewhere will likely be required to get things up
and running.

Emulab is being actively developed, so there may be features in deployed
Emulabs (in particular, Utah's) that are not included in this release.
Emulab is also a research project, and is rapidly evolving to satisfy the
needs of both our research needs and external researchers.  For that reason,
you might find bugs!  We hope you will tell us about them (nicely) and maybe
even help us to fix them.  More on this below.


HOW TO SETUP AN EMULAB
The Emulab installation documentation is located on the Utah Emulab Wiki:
    https://users.emulab.net/trac/emulab/wiki/InstallRoot


HOW TO UPDATE AN EMULAB
Updating your existing Emulab is a bit harder than a fresh install, but is
mostly automated.  A process that we hope will work for most sites is
located on the Utah Emulab Wiki:
    http://users.emulab.net/trac/emulab/wiki/InstallRoot
under "Upgrade Documentation."


TRACKING THE EMULAB SOURCE CODE
We encourage you to track the Emulab source code in real time and stay
current with our stable versions.  More info on how to access the
Emulab source code repository is here:
    http://users.emulab.net/trac/emulab/wiki/GitRepository


MAILING LISTS
If you are bringing up an Emulab, be sure to join the mailing list:
    emulab-admins@googlegroups.com
    http://groups.google.com/group/emulab-admins
which has open archives.

Users of your Emulab should join the Emulab users group, which is intended
for all users of Emulabs anywhere, to help each other:
    emulab-users@googlegroups.com
    http://groups.google.com/group/emulab-users


HELP/CONTACT INFORMATION
For help and to report bugs and problems, mail to
    emulab-admins@googlegroups.com

Don't be shy!  In most cases, you will have the same questions other people
have.  Search the archives, too!  There is lots of good information there.


COPYRIGHT, LICENSE, AND DISTRIBUTION
Emulab is copyrighted by the Flux Research Group and the University of Utah.

This release of the Emulab software is distributed under the terms of the GNU
Affero General Public License, version 3 (AGPLv3).  The AGPLv3 is a popular
open source license; see the file AGPL-COPYING for licensing conditions.  The
AGPLv3 consists of the GNU General Public License version 3 (GPLv3) with a
single short addition (Section 13), which requires that the source be freely
available to all users who interact with the software through a network.

The Emulab source tree contains various third-party, open-source packages that
are used by Emulab.  These third-party packages are copyrighted and licensed as
described in their source files.

The development of Emulab has been supported by numerous organizations
including NSF, DARPA, Intel, HP, Microsoft, Novell, Nortel, and the University
of Utah.  We thank all of these organizations for making Emulab possible.

The following statement is required by DARPA and pertains to DARPA's support
for portions of the Emulab software:

    DoD Distribution Statement A: Approved for public release; distribution is
    unlimited.


DOCUMENTATION
All of the Emulab documentation is available from the Utah Emulab site:
    http://users.emulab.net/trac/emulab/wiki

We encourage people to help us improve our documentation.  If you want to
make changes, please apply for an account at Utah; anyone with an account
at the Utah Emulab is allowed to edit the Wiki pages.

Other good places to start would include:
  - The search box at www.emulab.net
  - The Emulab Wiki (http://users.emulab.net/trac/emulab/wiki)
  - Getting Started document (http://users.emulab.net/trac/emulab/wiki/Auth)
  - The user tutorial (http://users.emulab.net/trac/emulab/wiki/Tutorial)
  - The user FAQ (http://users.emulab.net/trac/emulab/wiki/FAQ)
  - Papers and talks about Emulab (http://www.emulab.net/pubs.php3)
  - Papers using Emulab (http://www.emulab.net/expubs.php)


QUICK TOUR
 - The database maintains most testbed state.
   * Assorted modules (db/*.pm.in) are the main DB interface for testbed
     software.
   * sql/database-create.sql contains the DB schema.

 - The Web interface (www/*) is the primary means of managing and
   interfacing with the system.  There is also an experimental
   standalone GUI that uses this interface.

 - The tbsetup and backend directories contain the bulk of the server-side
   experiment setup and management code.
   * startexp (tbsetup/startexp.in) is the back end for experiment creation.
     Important scripts it calls include tbprerun (tbsetup/tbprerun.in)
     and tbswap (tbsetup/tbswap.in).
   * ns2ir (tbsetup/ns2ir/*) converts NS files to DB state (via TCL and XML).
   * snmpit (tbsetup/snmpit.in) configures VLANs on switch hardware.

 - assign (assign/*) maps experiments to available hardware.

 - The frisbee subsystem (os/frisbee.redux, os/imagezip) is used for the
   creation and rapid deployment of disk images.

 - The client-driven node configuration is handled by scripts on the client
   which communicate with the server via a custom configuration protocol.
   The server- and client-side of this mechanism is in the tmcd subdir.

 - capture and console (capture/*, tip/*) provide serial line access to nodes.

 - dynamic node and experiment control is provided via the Emulab event
   system and its assorted agents (event/*).


SOURCE TREE ORGANIZATION
account   -  Account creation and management
apache    -  Apache HTTPD configuration
assign    -  Resource allocation software
backend   -  Server-side of the Emulab XML-RPC interface
bugdb     -  Optional per-project bug database
capture   -  Node serial line server software
cdrom     -  Software related to CD-booting local and remote machines
collab    -  Optional per-project "collaboration" tools: CVS, jabber, mailman
db        -  Variety of interfaces to testbed state
delay     -  RHL9 patches for supporting "end-node" traffic shaping
dhcpd     -  DHCPD configuration
doc       -  Documentation (mainly internal)
event     -  Event System
firewall  -  Code and notes for per-experiment control net firewalls
flash     -  Software related to flash-dongle-booting local and remote machines
hyperviewer - 3D experiment visualization tool (not used)
image-test - Test framework for auto-testing of new OS images
install   -  Site installation scripts
ipod      -  "Ping of Death" software/patches
lib       -  C/C++ interface libraries
mote      -  Initial testbed support for Berkeley/Crossbow motes
named     -  BIND configuration files
os        -  Client-side software (disk loading, route calculation, etc.)
patches   -  Patches needed to compile standard software packages
pelab     -  Preliminary support for "Flexlab," an Emulab/PlanetLab hybrid
               (see http://www.cs.utah.edu/flux/flexlab/)
protogeni -  Evolving software for a prototype GENI system based on Emulab
               (see http://www.protogeni.net/)
pxe       -  Software related to PXE-booting machines
rc.d      -  Server-side startup scripts
robots    -  Support for mobile wireless (Garcia robots)
security  -  Tools for secure boss node access
sensors   -  Node monitoring daemons
sql       -  Database schema and initialization
ssl       -  SSL Certificate configurations
sysadmin  -  Apache Log Roller
tbsetup   -  Experiment creation and manipulation
testsuite -  Automated testing suite
tip       -  Node serial line client software
tmcd      -  Testbed master control daemon and client (for node configuration)
tools     -  Miscellaneous infrastructure tools
utils     -  Testbed configuration and maintenance tools
vis       -  Experiment visualization
wiki      -  Support for per-project Wikis
www       -  Web Interface / User Documentation
xmlrpc    -  Programatic XML-RPC interface to testbed

Good luck!
The Emulab Team