Newer
Older
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
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.
Emulab is also a research project, and is rapidly evolving to satisfy the
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.
The Emulab installation documentation is located on the Utah Emulab Wiki:
https://users.emulab.net/trac/emulab/wiki/InstallRoot
Updating your existing Emulab is a bit harder than a fresh install, but is
mostly automated. A process that we hope will work for most sites is
http://users.emulab.net/trac/emulab/wiki/InstallRoot
under "Upgrade Documentation."
TRACKING THE EMULAB SOURCE CODE
We encourage you to track the Emulab source code in real time and stay
current with our stable versions. More info on how to access the
Emulab source code repository is here:
http://users.emulab.net/trac/emulab/wiki/GitRepository
MAILING LISTS
If you are bringing up an Emulab, be sure to join the mailing list:
emulab-admins@googlegroups.com
http://groups.google.com/group/emulab-admins
Users of your Emulab should join the Emulab users group, which is intended
for all users of Emulabs anywhere, to help each other:
http://groups.google.com/group/emulab-users
For help and to report bugs and problems, mail to
Don't be shy! In most cases, you will have the same questions other people
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
available to all users who interact with the software through a network.
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.
All of the Emulab documentation is available from the Utah Emulab site:
We encourage people to help us improve our documentation. If you want to
make changes, please apply for an account at Utah; anyone with an account
at the Utah Emulab is allowed to edit the Wiki pages.
Other good places to start would include:
- 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)
- The database maintains most testbed state.
* 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
- The tbsetup and backend directories contain the bulk of the server-side
experiment setup and management code.
* startexp (tbsetup/startexp.in) is the back end 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.
- The frisbee subsystem (os/frisbee.redux, os/imagezip) is used for the
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
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
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
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
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)
utils - Testbed configuration and maintenance tools
xmlrpc - Programatic XML-RPC interface to testbed