Commit 25592f98 authored by Ian Murdock's avatar Ian Murdock

Added README and design overview.

parent aaa1a65d
OVERVIEW
********
The testbed event system is composed of four parts: (1) the event
library, which implements a simple, transport-independent API that
clients may use to trigger and respond to events; (2) the event
scheduler, which takes a list of events as input and triggers
the events at the appropriate times; (3) frontends that take events
specified by the user as input and pass them to the event scheduler;
and (4) backends that respond to various system events on behalf of
the testbed. Each of these four parts are described in more detail
in the following sections.
Event library
=============
Clients in the system trigger and respond to events using the event
library. The event library is currently implemented as a layer above
the Elvin publish/subscribe system (see "ELVIN OVERVIEW" below for a
brief overview of how Elvin works). A library and API separate from
Elvin exists for several reasons:
- The event library provides a much simpler interface than Elvin,
providing only the functionality that should be needed in
the testbed. This should make it significantly easier to write
clients that use the event system.
- The event library API is independent of Elvin, so if we change
to a system other than Elvin in the future (or write our own),
only the event library will need to be ported. In particular,
no event system clients should need to be changed.
- The event library API is significantly simpler than the Elvin
API, so it should be much easier to implement in environments
such as the Linux kernel, the OSKit, or Scout.
The event library is currently available as a C library on Unix. We
will add other language bindings as needed, and eventually
provide kernel support for Linux, FreeBSD, and the OSKit (see TODO).
The C API is described in the API file.
Event representation
--------------------
Events are represented by Elvin notifications that contain three
system defined fields: (1) "time", which specifies the time at which
the event should be/was fired; (2) "host", which specifies the
hostname of the testbed node that should receive the event
notification, or "*" if the event notification should be sent to all
nodes; and (3) "type", which specifics the event type (see "EVENT
TYPES" for a description of supported event types). In addition to
the system defined fields, event notifications may contain additional
attributes (in the form of name/value pairs) that may be used to
provide additional information about the event that has occurred.
Event scheduler
===============
The event scheduler is an event system client responsible for
triggering future events. The event scheduler reads a list of static
events written to the database by the frontend and triggers the
specified events at the appropriate times. In the future,
the event scheduler could be extended to support the scheduling
of dynamic events via an event library API call.
Frontend support
================
The frontend for static events is the NS script. Frontend support for
static events consists of a set of modifications to the NS parser that
extracts events from the NS script and writes them to the database for
processing by the event scheduler. For example, the NS command
$ns at 0.5 "$cbr0 start"
causes a event with time=0.5, type=TRAFGEN_START, and host=<hostname
of the node $cbr0 is attached to> to be written to the database; the
event scheduler then reads the event from the database and schedules
the TRAFGEN_START event to be fired at time 0.5 seconds.
The frontend for dynamic events could be a GUI that either triggers
events directly (using the event library) or schedules events to be
triggered in the future (using the event scheduler).
Backend support
===============
The backends are event system clients responsible for responding to
certain events on behalf of the testbed. For example, traffic
generation nodes are event system backends that start generating
traffic when they receive the TRAFGEN_START event notification
and stop generating traffic when they receive the TRAFGEN_STOP
event notification.
EVENT TYPES
***********
(in progress)
ELVIN OVERVIEW
**************
The testbed event system currently uses the Elvin publish/subscribe
system for communicating between event producers and event consumers.
Elvin uses a client/server architecture for delivering notifications.
The server accepts subscriptions from clients and routes notifications
from producers to the consumers that wish to receive them.
Notifications are arbitrary-length lists of name/value pairs (e.g.,
"type: NODE_FAILED, time: 23"), and subscriptions are expressed using
a simple syntax (e.g., "type == NODE_FAILED && time > 20"). Clients
can be both producers and consumers in the same session. Clients may
be written in C, C++, Java, Python, and Emacs Lisp. For more
information about how Elvin works, please see http://elvin.dstc.com/.
Elvin supports wide-area federations of Elvin servers; we can use this
feature to enable a global event namespace across multiple testbeds in
different geographic locations when the time comes.
This directory contains the testbed event system.
BUILDING THE EVENT SYSTEM
To build the event system, you first need to obtain the Elvin publish/
subscribe system. You need both the Elvin client library (libelvin)
and the Elvin server (elvind). You may either get them directly from
http://elvin.dstc.com/ or from the Flux CVS repository (module names
"libelvin" and "elvind"). Once the Elvin client library is built and
installed, you may build the event system by doing a "make".
USING THE EVENT SYSTEM
Before you may use the event system, you must configure the Elvin
server. A sample configuration file may be found in the etc
directory. The important parts are (1) to specify a scope
of "testbed", because that's the scope the event library operates
in; and (2) to set the "default" parameter to "on", so
that clients may find the server without having to specify a URL.
Next, you need to start the Elvin server ("elvind") and the event
scheduler ("event-sched") on a machine in the local network.
The Elvin server is the component responsible for routing event
notifications from event producers to event consumers; the event
scheduler is the component responsible for triggering system
events at the appropriate times. Once these two daemons are
running, clients in the system may use the event library to subscribe
to system events, and to trigger and respond to their own events as
well. For an overview of how the system works, please see the DESIGN
file.
Clients use the event library to interface with the event system; for
a description of the API, see the API file. Clients that need
additional functionality may also use Elvin directly, though at some
point in the future we may adopt a different system for event
notification transport or write our own. If you find that you
can't do something with the event library, then it very well
could be a limitation in the event library API; please contact
testbed-ops@fast.cs.utah.edu to let us know about it.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment