README 7.98 KB
Newer Older
1
Welcome to Emulab!
2

3 4
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
5
other sites around the world.
6

7
    http://www.emulab.net/
8

9
This is a snapshot of a rapidly evolving system.  It contains all Emulab
Jay Lepreau's avatar
Jay Lepreau committed
10
source required to build a running testbed, but interaction with Emulab
11 12
admins at Utah and elsewhere will likely be required to get things up
and running.
13

Jay Lepreau's avatar
Jay Lepreau committed
14 15
Emulab is being actively developed, so there may be features in deployed
Emulabs (in particular, Utah's) that are not included in this release.
16
Emulab is also a research project, and is rapidly evolving to satisfy the
17 18 19
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.
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
    https://users.emulab.net/trac/emulab/wiki/InstallRoot

26

Jay Lepreau's avatar
Jay Lepreau committed
27
HOW TO UPDATE AN EMULAB
28
Updating your existing Emulab is a bit harder than a fresh install, but is
29
mostly automated.  A process that we hope will work for most sites is
30
located on the Utah Emulab Wiki:
31 32 33
    http://users.emulab.net/trac/emulab/wiki/InstallRoot
under "Upgrade Documentation."

Jay Lepreau's avatar
Jay Lepreau committed
34

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

41

Jay Lepreau's avatar
Jay Lepreau committed
42 43
MAILING LISTS
If you are bringing up an Emulab, be sure to join the mailing list:
44 45
    emulab-admins@googlegroups.com
    http://groups.google.com/group/emulab-admins
Jay Lepreau's avatar
Jay Lepreau committed
46 47
which has open archives.

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

Jay Lepreau's avatar
Jay Lepreau committed
53 54

HELP/CONTACT INFORMATION
55
For help and to report bugs and problems, mail to
56
    emulab-admins@googlegroups.com
Jay Lepreau's avatar
Jay Lepreau committed
57

58
Don't be shy!  In most cases, you will have the same questions other people
59 60 61 62 63 64 65 66 67 68 69
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
Jay Lepreau's avatar
Jay Lepreau committed
70 71
available to all users who interact with the software through a network.

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
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.


Jay Lepreau's avatar
Jay Lepreau committed
87
DOCUMENTATION
88
All of the Emulab documentation is available from the Utah Emulab site:
89
    http://users.emulab.net/trac/emulab/wiki
90

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

95
Other good places to start would include:
96 97 98 99 100 101 102
  - 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)
Chad Barb's avatar
Chad Barb committed
103

104

Chad Barb's avatar
Chad Barb committed
105
QUICK TOUR
106
 - The database maintains most testbed state.
107 108
   * Assorted modules (db/*.pm.in) are the main DB interface for testbed
     software.
109
   * sql/database-create.sql contains the DB schema.
110 111 112

 - The Web interface (www/*) is the primary means of managing and
   interfacing with the system.  There is also an experimental
Leigh Stoller's avatar
Leigh Stoller committed
113
   standalone GUI that uses this interface.
114

115 116
 - The tbsetup and backend directories contain the bulk of the server-side
   experiment setup and management code.
117 118
   * startexp (tbsetup/startexp.in) is the back end for experiment creation.
     Important scripts it calls include tbprerun (tbsetup/tbprerun.in)
119 120 121
     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.
Chad Barb's avatar
Chad Barb committed
122 123

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

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

128 129 130
 - 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.
131

Chad Barb's avatar
Chad Barb committed
132 133
 - capture and console (capture/*, tip/*) provide serial line access to nodes.

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

137

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

Jay Lepreau's avatar
Jay Lepreau committed
186
Good luck!
187
The Emulab Team