Emulab network testbed source release
Version 5.0
September 1, 2008
University of Utah, Flux Research Group

This is the first "official" release of the full current source code for the
software that runs the Emulab network testbed at the University of Utah,
as well as over 20 testbeds at other sites:

   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.
In the future it is our intention to make new snapshots frequently.


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

HOW TO UPDATE AN EMULAB
Updating your existing Emulab is a bit harder than a fresh install,
as different sites are running different combinations of FreeBSD,
FreeBSD ports, and Emulab software.  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".

MAILING LISTS
If you are bringing up an Emulab, be sure to join the mailing list:
    testbed-admins@flux.utah.edu
    http://www.flux.utah.edu/mailman/listinfo/testbed-admins
which has open archives.


HELP/CONTACT INFORMATION
For help and to report bugs and problems, mail
   testbed-admins@flux.utah.edu   (preferable)
      or
   testbed-ops@flux.utah.edu      (if you insist on privacy)

Don't be shy!  We may be able to get on the phone with you, too,
for "big picture" issues and problems.


LICENSE
See the file AGPL-COPYING for licensing conditions.  In summary, the
Emulab software is distributed under a free and open source license, the
GNU Affero General Public License version 3 (AGPLv3).  The AGPLv3
consists of the GNU General Public License version 3 (GPLv3) with a
single short added Section 13, which requires that the source be freely
available to all users who interact with the software through a network.


DOCUMENTATION
We are in the process of moving all our documentation to the Utah Emulab
wiki at
  http://users.emulab.net/trac/emulab/wiki/ .
Soon, but not yet, that should be considered the primary source of
information.

Within this source tree,
- doc/* contains documentation for developers.
- www/*.html and www/{doc,tutorial}/*.html contain end-user documentation,
  all linked from www/doc.php3.

Other good places to start would include:
  - The search box at www.emulab.net for the absolutely latest FAQs and info
  - The user tutorial (www/tutorial/tutorial.html)
  - The user FAQ (www/faq.html)
  - The user authorization document (www/auth.html)
  - Software architecture preliminary diagram (doc/arch-diagram.ps)
  - Notes on the source tree and architecture (doc/arch.txt)
  - Overview of some major systems (doc/overview.txt)
  - The doc/papers directory, which contains a few of the papers we've
    published about Emulab  
  - Diagrams and brief explanations of the state machines used in the 
    system (www/doc/states.html and www/doc/*.gif)
  - Mail we have exchanged with others about hardware recommendations
    (doc/hardware-mail.mbox)


QUICK TOUR
 - The Database maintains most testbed state.
   * LibDB (db/libdb.pm.in) and the 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 backend 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 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

UPGRADING FROM the 4.9.0 RELEASE
There are a surprising number of differences given that we have only
advanced 0.1 in version!  In a nutshell:

 * Updated FreeBSD packages from FreeBSD 6.1-era to 6.3-era
 * Much more of the documentation has moved into the Wiki
 * Changes to the (unused) "protogeni" code
 * Improvements to the installation scripts
 * Integration of code/fixes from Keith Sklower and DETER (Thanks!)
 * Assorted fixes

If you did install the 4.9 release on FreeBSD 6.3, and want to upgrade
to 5.0 (you should), it should be straightforward.  You will need to apply
the sql/database-migrate.txt changes 4.157 to 4.160 (which are all trivial)
and rebuild and reinstall your Emulab software.

It would be good to also update your ports.  In theory, this is all handled
by a magic script we provide.  Refer to the "Update ports" section of
  http://users.emulab.net/trac/emulab/wiki/appendix/upgrade-410-63.html

Good luck!
Jay Lepreau, lepreau@cs.utah.edu, and the Utah testbed crew.
September 1, 2008