README 5.21 KB
Newer Older
1
This is a snapshot of the current source code for the software that runs
2 3
Netbed (Emulab++) at the University of Utah, as well as testbeds at other
sites:
4 5
   http://www.emulab.net/

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

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

16 17 18 19 20 21 22 23 24

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,
and return improvements to us.  These terms may become more
liberal in a future formal release.


25
HOW TO SETUP
26
Copy and localize the 'defs-example' file for your environment
27
and run "./configure".  See doc/setup.txt for details.
28

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

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
  - The doc/papers directory, which contains papers published about Netbed
45 46 47
  - The user tutorial (www/tutorial/tutorial.html)
  - The user FAQ (www/faq.html)
  - The user authorization document (www/auth.html)
48 49 50 51
  - 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".
52 53 54
  - 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)
55 56
  - Diagrams and brief explanations of the state machines used in the 
    system (www/doc/states.html and www/doc/*.gif)
57
  - The instructions for building a running system from scratch (doc/setup*.txt)
58 59
  - Mail we have exchanged with others about hardware recommendations
    (doc/hardware-mail.mbox)
60 61 62 63 64 65 66

QUICK TOUR
 - The Database maintains most testbed state.
   - LibDB (db/libdb.pm.in) is 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 the system.   
67

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
 - 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). 
 - assign (assign/*) maps experiments to available hardware.
 - snmpit (tbsetup/snmpit.in) configures VLANs on switch hardware.
 - frisbee (os/frisbee.redux/*) uses multicast to rapidly deploy disk images.
 - tmcd (tmcd/*) is contacted by nodes as they boot up, to get configuration.
 - capture and console (capture/*, tip/*) provide serial line access to nodes.

SOURCE TREE ORGANIZATION
account   -  Account creation and management
apache    -  Apache HTTPD configuration
assign    -  Resource allocation software
capture   -  Node serial line server software
84
cdrom     -  Software related to CD-booting local and remote machines
85 86 87 88
db        -  Variety of interfaces to testbed state 
dhcpd     -  DHCPD configuration
doc       -  Documentation (mainly internal)
event     -  Event System
89
hyperviewer - 3D experiment visualization tool
90 91 92
install   -  Site installation scripts
ipod      -  "Ping of Death" software
ir        -  NS-to-database interpreter (in TCL)
93 94 95 96 97 98 99
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
pxe       -  Software related to PXE-booting machines
rc.d      -  Server-side startup scripts
100 101 102 103 104 105 106 107
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
108 109
tmcd      -  Testbed master control daemon and client (for node configuration)
tools     -  Misc. infrastructure tools
110 111 112
utils     -  Testbed configuration and maintenence tools
vis       -  Experiment visualization
www       -  Web Interface / User Documentation
113
xmlrpc    -  Programatic XML-RPC interface to testbed
114

115
HELP/CONTACT INFORMATION
116
For help and to report bugs and problems, mail
117
    testbed-ops@flux.utah.edu
118

119
Don't be shy!  
120 121 122
We are happy to get on the phone with you, too,
for "big picture" issues and problems.

123
Jay Lepreau, lepreau@cs.utah.edu, 801-581-4285, and the Utah testbed crew.
124 125
February 1, 2004
]