Emulab network testbed source release Version 5.0 September 1, 2008 University of Utah, Flux Research Group This is the first "official" release of the full current source code for the software that runs the Emulab network testbed at the University of Utah, as well as over 20 testbeds at other sites: http://www.emulab.net/ 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. In the future it is our intention to make new snapshots frequently. HOW TO SETUP AN EMULAB The Emulab installation documentation is located on the Utah Emulab Wiki: http://users.emulab.net/trac/emulab/wiki/InstallRoot under "Installation Documentation". HOW TO UPDATE AN EMULAB 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". 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) Don't be shy! We may be able to get on the phone with you, too, 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 We are in the process of moving all our documentation to the Utah Emulab wiki at http://users.emulab.net/trac/emulab/wiki/ . Soon, but not yet, that should be considered the primary source of information. 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. Other good places to start would include: - The search box at www.emulab.net for the absolutely latest FAQs and info - The user tutorial (www/tutorial/tutorial.html) - The user FAQ (www/faq.html) - The user authorization document (www/auth.html) - 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) - The doc/papers directory, which contains a few of the papers we've published about Emulab - Diagrams and brief explanations of the state machines used in the system (www/doc/states.html and www/doc/*.gif) - Mail we have exchanged with others about hardware recommendations (doc/hardware-mail.mbox) QUICK TOUR - The Database maintains most testbed state. * 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. - The Web Interface (www/*) is the primary means of managing and interfacing with the system. There is also an experimental standalone GUI that uses this interface. - The tbsetup and backend directories contain 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. - assign (assign/*) maps experiments to available hardware. - The frisbee subsystem (os/frisbee.redux, os/imagezip) is used for 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 capture - Node serial line server software 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 install - Site installation scripts 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 (see http://www.cs.utah.edu/flux/flexlab/) 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 robots - Support for mobile wireless (Garcia robots) 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) tools - Miscellaneous infrastructure tools utils - Testbed configuration and maintenance tools vis - Experiment visualization wiki - Support for per-project WIKIs www - Web Interface / User Documentation xmlrpc - Programatic XML-RPC interface to testbed 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 Good luck! Jay Lepreau, lepreau@cs.utah.edu, and the Utah testbed crew. September 1, 2008
Forked from
emulab / emulab-devel
18303 commits behind the upstream repository.
Robert Ricci
authored