MASH Server
The MASH Server is an HTTP server that allows user to access
MASH tools via the Web. The server currently supports are the
following tools:
- SDR - session announcement agent
- MSP - session viewing tool
- ARIES - recording agent
- MARS - archive playback tool
With these tools, a user is able to select from a list of
announcements, view and/or record a session, and play archived
sessions from the user's Web browser. Since the server is a
Web-based tool, user operation is relatively self-explanatory.
Therefore, this document provides information required for running the server and augmenting
its functionality.
1. Running the Server
The following section provides step-by-step instructions on
how to run the MASH Server and the supporting status checker
which periodically polls the server for its status and restarts
the server when it goes down.
- Copy the sample prefs file to the ~/.mash/ directory; this file
is located in the following directory: mash/tcl/applications/mash_server/.
- Make appropriate changes to the prefs file; the various
fields of the prefs file are described in Appendix A.
- From the mash
directory, type "make
mash_server."
- Run the server by typing "mash_server >& [output
dir]/output.txt &." The server currently
defaults to port 4444. Note that the output dir is that
wihch is specified in the prefs file.
- From the mash
directory. run the status checker by typing "bin/smash
tcl/applications/mash_server/status_checker.tcl >&
[output dir]/status_output.txt &"
2. Augmenting the Server's Functionality
This section covers the steps required to add a new Agent to
the MASH Server. This begins with a description of the overall structure of the server, followed
by information useful in writing a MASH
HTTP_Agent, and finally instructions for adding
the new Agent to the server.
2.1. The Overall Structure
The MASH Server basically acts as a frontend to the Web which
MASH HTTP_Agents are able to plug into. When the it receives a
HTTP request, the server simply passes relevant information
extracted from the URL to each of the Agents. The URL and
associated information are then examined by each Agent to
determine whether the request is relevant to that Agent's
funcationlity. This is done through a mechanism of "magic
URLs." A typical magic URL takes the following forms:
http://spade:4444/[dynamic
or non-dynamic html page]
http://spade:4444/[function]^[SDP Message unique key]
2.2. Writing an HTTP_Agent
The only requirement of an HTTP Agent that plugs into the MASH
Server is that it has a handle_request method. This method takes
as arguemnts a url, key, and source and returns a list containg
the page, status, and type. These arguemtsn and return values are
described in more detail below:
- url: this is either an html page or the function name
portion of the request (i.e. that which comes before the
^)
- key: this is the argument that follows the ^; typically
this is some unique key which identifies the object on
which some action will be performed.
- source: the machine name of the requestor's source
- page: the HTML page or data that is to be returned
- status: the numerical HTTP return code (e.g. 200 = OK)
- type: the mimetype of the page or data being returned
(e.g. text/html)
Although, the handle_request method is the only requirement
for HTTP Agents, one may find it useful to derive the new Agent
from the HTTP_Agent class. This class contains some helper
functionsn that the writer of the new Agent may find helpful.
Please refer to http_agent.tcl for more information on these
functions and their usage.
2.3. Adding an Agent to the
Server
In main.tcl of the
mash_server directory, do the following:
- Create an instance of the new Agent.
- Add the agent with the command "$server add_agent [your agent]."
Appendix A: Prefs Fields
- html_dir: the directory in which the dynamic and
non-dynamic HTML files are stored
- archive_root: the main archive directory
- archive_dir: the subdirectory within the main archive
directory where recording agent stores recorded sessions
- sdp_sessions_dir: the sdr agent's cache
- rec_schedule_dir: the directory that the recording agent
uses to store a schedule of current and future recordings
- play_server_addr: the multicast address used by MARS
- max_duration: the maximum duration for recordings in
minutes
- email_addr: the email address to which status
notifications are sent
- output_dir: the directory in which status_checker and
mash_server is redirected
- server_addr: the MASH Server's address
- server_port: the MASH Server's port
- mashlet_dir: the URL that will be used as the TCLCL_IMPORT_DIRS
environment variable in dynamically generated mashlets
- ping_freq: the frequency (in seconds) at which the
status_checker polls the server
- valid_clients: a regular expression describing from which
machines recording is allowed