README 6.36 KB
Newer Older
1
This is a snapshot of the current source code for the software that runs
2 3
Emulab at the University of Utah, as well as testbeds at other sites:

4 5
   http://www.emulab.net/

6
This is a snapshot of a rapidly-evolving system, rather than an engineered
7
release. It contains all Emulab source required to build a running testbed, but
8 9 10
interaction with Utah will almost certainly be required to get things up and
running.

11 12 13 14
Emulab is being actively developed, so there will be features on deployed
Emulabs (in particular, Utah's) that are not included in this snapshot.
Contact us (contact info at the bottom of this file) if you are interested
in receiving an updated version of this source.
15

Jay Lepreau's avatar
Jay Lepreau committed
16 17 18 19 20

IMPORTANT NOTE
See the file LICENSE for restrictions on this snapshot.
In summary, you can't redistribute it, use it for commercial
purposes, must give appropriate credit to Utah and Emulab,
21 22 23
and return improvements to us.  The intention is to release
the Emulab software under the AGPLv3 open source license
Real Soon Now.
Jay Lepreau's avatar
Jay Lepreau committed
24 25


26
HOW TO SETUP
27
See doc/setup.txt.
28

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

33 34 35
HOW TO UPDATE
Start by looking at doc/update-testbed.txt.

36
DOCUMENTATION
37
This is a snapshot, not a formal distribution, so don't expect
38 39 40 41
great documentation.

doc/* contains documentation for developers.
www/*.html and www/doc/*.html contain end-user documentation.
42 43

Good places to start would include:
44 45
  - The search box at www.emulab.net for the absolute latest FAQs and info
  - The doc/papers directory, which contains papers published about Emulab
46 47 48
  - The user tutorial (www/tutorial/tutorial.html)
  - The user FAQ (www/faq.html)
  - The user authorization document (www/auth.html)
49 50 51 52
  - Some powerpoint slides on Emulab internals, found at:
      http://www.cs.utah.edu/flux/testbed-doc/internals/
    These include two files especially useful for setting up your own
    testbed: "build-operate.ppt" and the first part of "security-all.ppt".
53 54 55
  - 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)
56 57
  - Diagrams and brief explanations of the state machines used in the 
    system (www/doc/states.html and www/doc/*.gif)
58 59
  - The instructions for building a running system from scratch
    (doc/setup*.txt)
60 61
  - Mail we have exchanged with others about hardware recommendations
    (doc/hardware-mail.mbox)
62

63 64 65 66
Join the testbed-admins@flux.utah.edu mailing list:

http://www.flux.utah.edu/mailman/listinfo/testbed-admins

67 68
QUICK TOUR
 - The Database maintains most testbed state.
69 70 71
   * 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.
72
   
73 74
 - The Web Interface (www/*) is the primary means of managing and
   interfacing with the system.
75

76 77 78 79 80 81 82
 - The tbsetup directory contains the bulk of the server-side experiment
   setup and management code.
   * 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.
83 84

 - assign (assign/*) maps experiments to available hardware.
85 86 87 88

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

89
 - tmcd (tmcd/*) is contacted by nodes as they boot up, to get configuration.
90

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

93 94 95 96 97 98
 - The majority of the client-side (i.e., on each experiment node) boot-time
   setup code is in the tmcd/common and tmcd/<os-name> directories.  These
   are mostly perl and sh scripts for adding accounts, configuring interfaces,
   installing software, etc.


99 100 101 102
SOURCE TREE ORGANIZATION
account   -  Account creation and management
apache    -  Apache HTTPD configuration
assign    -  Resource allocation software
103
bugdb     -  Optional per-project bug database
104
capture   -  Node serial line server software
105
cdrom     -  Software related to CD-booting local and remote machines
106
collab    -  Optional per-project "collaboration" tools: CVS, jabber, mailman
107
db        -  Variety of interfaces to testbed state 
108
delay     -  RHL9 patches for supporting "end-node" traffic shaping
109 110 111
dhcpd     -  DHCPD configuration
doc       -  Documentation (mainly internal)
event     -  Event System
112
firewall  -  Code and notes for per-experiment control net firewalls
113
hyperviewer - 3D experiment visualization tool
114
image-test - Test framework for auto-testing of new OS images
115
install   -  Site installation scripts
116
ipod      -  "Ping of Death" software/patches
117 118 119 120 121
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
122 123
pelab     -  Preliminary support for "Flexlab"; an Emulab/PlanetLab hybrid
             (http://www.cs.utah.edu/flux/flexlab/)
124 125
pxe       -  Software related to PXE-booting machines
rc.d      -  Server-side startup scripts
126
robots    -  Initial testbed support for mobile wireless (Garcia robots)
127 128 129 130 131 132 133 134
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
135 136
tmcd      -  Testbed master control daemon and client (for node configuration)
tools     -  Misc. infrastructure tools
137
utils     -  Testbed configuration and maintenance tools
138
vis       -  Experiment visualization
139
wiki      -  Support for per-project WIKIs
140
www       -  Web Interface / User Documentation
141
xmlrpc    -  Programatic XML-RPC interface to testbed
142

143
HELP/CONTACT INFORMATION
144
For help and to report bugs and problems, mail
145
    testbed-ops@flux.utah.edu
146

147
Don't be shy!  
148 149 150
We are happy to get on the phone with you, too,
for "big picture" issues and problems.

151
Jay Lepreau, lepreau@cs.utah.edu, 801-581-4285, and the Utah testbed crew.
152
June 12, 2007