README 7.21 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

6
This is a preliminary release of the full current source code for the
Jay Lepreau's avatar
Jay Lepreau committed
7 8
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
This is a snapshot of a rapidly-evolving system.  It contains all Emulab
source required to build a running testbed, but interaction with Emulab
14 15
admins at Utah and elsewhere will likely be required to get things up
and running.
16

Jay Lepreau's avatar
Jay Lepreau committed
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.
19
In the future it is our intention to make new snapshots frequently.
20 21


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

26

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

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


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

Jay Lepreau's avatar
Jay Lepreau committed
48 49 50 51 52 53 54 55 56 57 58 59 60 61
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
62 63 64
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.
65

66 67 68 69
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.
70

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

85

86 87
QUICK TOUR
 - The Database maintains most testbed state.
88 89 90
   * 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.
91
   
92
 - The Web Interface (www/*) is the primary means of managing and
93 94 95
   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.
96

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

 - assign (assign/*) maps experiments to available hardware.
106 107 108 109

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

110 111 112
 - 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.
113

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

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

119

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


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