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

6
This is the first "official" 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
The Emulab installation documentation is located on the Utah Emulab Wiki:
24 25
 http://users.emulab.net/trac/emulab/wiki/InstallRoot
under "Installation Documentation".
26

Jay Lepreau's avatar
Jay Lepreau committed
27
HOW TO UPDATE AN EMULAB
28 29 30 31 32 33
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".
Jay Lepreau's avatar
Jay Lepreau committed
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

Leigh Stoller's avatar
Leigh Stoller committed
48
Don't be shy!  We may be able to get on the phone with you, too,
Jay Lepreau's avatar
Jay Lepreau committed
49 50 51 52 53 54 55 56 57 58 59 60 61
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
Leigh Stoller's avatar
Leigh Stoller committed
62 63
We are in the process of moving all our documentation to the Utah Emulab
wiki at
64
  http://users.emulab.net/trac/emulab/wiki/ .
Leigh Stoller's avatar
Leigh Stoller committed
65 66
Soon, but not yet, that should be considered the primary source of
information.
67

68 69 70 71
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.
72

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

88

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

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
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
189

Jay Lepreau's avatar
Jay Lepreau committed
190 191
Good luck!
Jay Lepreau, lepreau@cs.utah.edu, and the Utah testbed crew.
192
September 1, 2008
Robert Ricci's avatar
Robert Ricci committed
193