http.asc from EmStar at Krugle

Show http.asc syntax highlighted

The EmStar Web Interface
========================
mlukac at lecs cs ucla edu
$Id: http.asc,v 1.2 2004/10/26 22:28:53 mlukac Exp $

There is now a web interface available for determining the status of
your EmStar processes, changing processes log levels, as well as
allowing users to create an entire web based interface for their
applications.

KNOWN BUGS
----------

- Switching from browsing a host that is running a simulation to
browsing the same host that is running in non sim mode (i.e. no
SIM_GROUP set) will cause the cgi's to give errors and not work. To
get around this problem, simply use your browsers cookie browsing
features to delete the cookies for the particular host you are trying
to browse.

- There maybe problems if the host you are browsing does not have a
fully qualified domain name and are trying to run in sim mode. The
problem might be cause because we modified bozohttpd to redirect to
the fully qualified domain name because for cookies. If anything, you
can try using the ip. Otherwise please post to the emstar-users list
if you run across such a problem.

Building
--------

The EmStar Web Interface requires the cURL library and its development
headers. Most Linux distributions provide these as easily obtainable
packages called libcurl and libcurl-dev.

Once you have obtained and installed libcurl, uncomment the following
line from the devel/BUILD file:

------------
include {http}
------------

You have to make sure to have the devel directory enabled in the root
BUILD file as well.

* Compiling for the Stargate

The EmStar Web Interface does run on Stargates. However, libcurl is
not provided by default in any of the tool-chains or distributions. You
will need to obtain the libraries and headers either from the ipkg, or
the arm deb, modify the devel/http/BUILD file to look in the correct
places for these. Then you will also need to install the ipkg on your
Stargate.

For help with all this, please email the emstar-users list or Martin
at mlukac at lecs.cs.ucla.edu.

Setup
-----

* In Simulation Mode

If you are running in sim mode, and have successfully built the web
interface, it will automatically be started with each simulation you
run. You must have cookies enabled in your browser to successfully use
the interface.

*****
When running in sim mode, the web server is at port 8080 plus your
SIM_GROUP. For instance, if my SIM_GROUP is set to 12, you should
point your web browser to port 8092.
*****

* In Non-Simulation Mode

If you are running in non sim mode (no SIM_GROUP set, and using
emrun), add the following to your run files:

------------
include devel/http/http.run
&http();
------------

This will make the web server to startup and stop each time you start
and stop your node.

*****
When running in non sim mode, the web server is at port 8080
*****

Basic Usage
-----------

When running in simulation mode, you must have cookies enabled in your
browser. Simply point your web browser at the appropriate host and
port.

For instance, if I was running a simulation host called myhost with
SIM_GROUP=2, I would point my web browser to:

-------------
http://myhost:8082/
or
http://myhost:8082/cgi-bin/sim.cgi
-------------

I would then be presented with a list of running nodes and a list of
all the sim-components running.

If I was running in non sim mode, I would point my web browser to:

-------------
http://myhost:8080/
or
http://myhost:8080/cgi-bin/node.cgi
-------------

I would then be able to browse the standard services status devices
and view the logs for all your processes.

To interface with the status devices and command devices for your own
processes please see the following Advanced Usage section.

Advanced Usage
--------------

There are two ways to use the web interface for your own processes.

* using html = " ... " in your run files

You can add a tag to a process block which will add the tag value to
the display page for the process. This can be used to tell the web
interface which devices and how they should be displayed on a process
page.

There are a couple of cgi's which make display process information to
the process page easy.

Suppose we have a process which creates two devices: a status device
called webtest/mystatus, a command device called
webtest/mycommands. We want the status device to be cat'ed to the web
page. We want the command device to the cat'ed to the web page, and
then a form to actually send commands to the command device.

For status devices, there is a status.cgi with accepts a device
argument. To have the process page cat the status device, we write a
server side include using the status device as an argument.

html = "";

For command devices there is a command.cgi which is very similar to
the status.cgi. It is used in a server side include in a similar
manner:

html = "";

.Note
*****
An html output mode call back has been added to status devices. You
can use this to customize the html output of your status device, so
instead of just outputting plain ASCII, you can output valid html.
*****

So, my run file could contain:

--------------
include devel/http/http.run

...

&http();

...

process webtest {
waitfor = ls0;
type = once;
noclean
cmd = "devel/webtest/webtest --users udp0";
html = "";
html = "";
}
---------

This will add the two server side includes to the page that is
displayed when you click on the webtest process for the node. The
server side includes are then processed.

.Note
*****
There are no bindings between the cgi's and devices. For instance,
since the command device has similar semantics to a status device, you
could use the command.cgi to write to a status device.
*****

* using html_template = " ... " in your run files

To create your own web interface or application for a process use the
html_template tag. It allows you to break out of the normal emstar web
interface into your own html and cgi's. Using the value provided with
the tag, it creates a link on the node page. For instance, if I were
to add

html_template = "/cgi-bin/webtestcgi.cgi"

to my webtest process block, the next time the node/simulation is run,
the normal process link that takes you to the cat'ed devices and the
log, will be replaced with a link to the value of html_template.

You have to be careful if you are linking to a cgi. You are expected
to output almost everything. We will eventually have a basic example,
but for now, please follow the cgic link at the bottom of the page to
see how to write cgi's in straight C.

* available cgi documentation

List the various args that the built in cgi's can take. For instance,
status devices can take extra arguments with the arg= ... more to come
later.

If you wish to add another cgi to be used by the html tag, there is a
cgi_template.cgi file in devel/http/cgi which you can follow.

How It Works (a.k.a. What Is Going On)?
---------------------------------------

We run our own server side include (SSI) parser on all the html and
cgi files. This allows us to spread out the functionality between all
of the cgi's, and have all the cgi's reference each other by simply
printing their own SSI's.

Credits
-------

The EmStar Web Interface is made possible by the following software:
link:http://www.eterna.com.au/bozohttpd/[the bozotic HTTP server]
link:http://curl.haxx.se/libcurl/[libcURL - a multiprotocol file transfer library]
link:http://www.boutell.com/cgic/[cgic: an ANSI C library for CGI Programming]

See more files for this project here