README 7.28 KB
Newer Older
Jay Lepreau's avatar
Jay Lepreau committed
1 2 3 4
Emulab network testbed source release
Version 4.9.0
June 30, 2008
University of Utah, Flux Research Group
5

Jay Lepreau's avatar
Jay Lepreau committed
6 7 8
This is a preliminary release of the 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:
9

Jay Lepreau's avatar
Jay Lepreau committed
10
   http://www.emulab.net/
11

Jay Lepreau's avatar
Jay Lepreau committed
12 13 14
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 may be required to get things up and running.
15

Jay Lepreau's avatar
Jay Lepreau committed
16 17 18
Emulab is being actively developed, so there may be features in deployed
Emulabs (in particular, Utah's) that are not included in this release.
It is our intention to make new snapshots frequently, in the future.
19 20


Jay Lepreau's avatar
Jay Lepreau committed
21
HOW TO SETUP AN EMULAB
22 23 24
The Emulab installation documentation is located on the main Emulab Wiki.
See http://users.emulab.net/trac/emulab/wiki/InstallDocs

25

26
This source currently only builds on FreeBSD, and requires several packages;
27 28
the dependencies can be found in the Makefile for our 'meta-port's:
install/ports/emulab-boss and install/ports/emulab-ops.
29

30

Jay Lepreau's avatar
Jay Lepreau committed
31 32 33 34 35
HOW TO UPDATE AN EMULAB
The upcoming 5.0 release (intention to be in July 2008) will have better
support for people upgrading existing Emulabs.  We recommend you wait
for that; do not expect us to help much if you use this release.

36
If you insist, start by looking at doc/update-testbed.txt.
Jay Lepreau's avatar
Jay Lepreau committed
37 38 39 40 41 42 43 44 45 46 47 48 49 50


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)
51

Jay Lepreau's avatar
Jay Lepreau committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65
Don't be shy!  We may be able to get 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
66 67 68 69
We are in the process of moving our documentation to the Emulab wiki at
https://users.emulab.net/trac/emulab/wiki/.
This should be considered the primary source of information.

70 71
doc/* contains documentation for developers.
www/*.html and www/doc/*.html contain end-user documentation.
72

73
Other good places to start would include:
74 75
  - The search box at www.emulab.net for the absolute latest FAQs and info
  - The doc/papers directory, which contains papers published about Emulab
76 77 78
  - The user tutorial (www/tutorial/tutorial.html)
  - The user FAQ (www/faq.html)
  - The user authorization document (www/auth.html)
79 80 81
  - 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)
82 83
  - Diagrams and brief explanations of the state machines used in the 
    system (www/doc/states.html and www/doc/*.gif)
84 85
  - Mail we have exchanged with others about hardware recommendations
    (doc/hardware-mail.mbox)
86

87

88 89
QUICK TOUR
 - The Database maintains most testbed state.
90 91 92
   * 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.
93
   
94
 - The Web Interface (www/*) is the primary means of managing and
95 96 97
   interfacing with the system.  For the most part it uses an XML RPC
   interface (xmlrpc/*) for communicating with the "backend" infrastructure.
   There is also an experimental standalone GUI that uses this interface.
98

99 100
 - The tbsetup and backend directories contain the bulk of the server-side
   experiment setup and management code.
101 102 103 104 105
   * 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.
106 107

 - assign (assign/*) maps experiments to available hardware.
108 109 110 111

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

112 113 114
 - 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.
115

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

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

121 122 123 124
SOURCE TREE ORGANIZATION
account   -  Account creation and management
apache    -  Apache HTTPD configuration
assign    -  Resource allocation software
125
backend	  -  Server-side of the Emulab XML RPC interface
126
bugdb     -  Optional per-project bug database
127
capture   -  Node serial line server software
128
cdrom     -  Software related to CD-booting local and remote machines
129
collab    -  Optional per-project "collaboration" tools: CVS, jabber, mailman
130
db        -  Variety of interfaces to testbed state 
131
delay     -  RHL9 patches for supporting "end-node" traffic shaping
132 133 134
dhcpd     -  DHCPD configuration
doc       -  Documentation (mainly internal)
event     -  Event System
135
firewall  -  Code and notes for per-experiment control net firewalls
136
flash     -  Software related to flash-dongle-booting local and remote machines
Jay Lepreau's avatar
Jay Lepreau committed
137
hyperviewer - 3D experiment visualization tool (not used)
138
image-test - Test framework for auto-testing of new OS images
139
install   -  Site installation scripts
140
ipod      -  "Ping of Death" software/patches
141 142 143 144 145
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
Jay Lepreau's avatar
Jay Lepreau committed
146 147
pelab     -  Preliminary support for "Flexlab", an Emulab/PlanetLab hybrid
               (see http://www.cs.utah.edu/flux/flexlab/)
148 149
protogeni -  Evolving software for a prototype GENI system based on Emulab
               (see http://www.protogeni.net/)
150 151
pxe       -  Software related to PXE-booting machines
rc.d      -  Server-side startup scripts
Jay Lepreau's avatar
Jay Lepreau committed
152
robots    -  Support for mobile wireless (Garcia robots)
153 154 155 156 157 158 159 160
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
161
tmcd      -  Testbed master control daemon and client (for node configuration)
Jay Lepreau's avatar
Jay Lepreau committed
162
tools     -  Miscellaneous infrastructure tools
163
utils     -  Testbed configuration and maintenance tools
164
vis       -  Experiment visualization
165
wiki      -  Support for per-project WIKIs
166
www       -  Web Interface / User Documentation
167
xmlrpc    -  Programatic XML-RPC interface to testbed
168 169


Jay Lepreau's avatar
Jay Lepreau committed
170 171 172
Good luck!
Jay Lepreau, lepreau@cs.utah.edu, and the Utah testbed crew.
June 30, 2008