The ServiceMail(tm) Toolkit, v1.2 10-13-92

Jay C. Weber <weber@eitech.com>
Eric Rescorla <ekr@eitech.com> 
Salil Deshpande <salil@eitech.com>
Enterprise Integration Technologies (EIT)

This distribution contains software that helps you set up servers that
others can access via electronic mail.  Such servers can include archive
servers and mailing-list maintainers (for which code is included in this
distribution), but also custom services like solid modelers, text
formatters, simulators, etc.  In fact, earlier versions of this distribution
were used to create the following email services:

 o a semiconductor process simulator at Stanford University

 o a PDES-described solid rendering service at the University of Utah

 o an image-to-text (OCR) service at Cornell

 o a LaTeX-to-Postscript compiler, an FTP gateway, a WAIS gateway,
   a stock quote service, etc. at EIT

We hope you will think of many other batch-oriented services that your
organization can provide to the world.  The advantage of the use of email
access is, of course, is its ubiquity; virtually all of the roughly
five million world-wide Internet users (on roughly 750,000 machines) would
then be able to run your software prototype, retrieve your technical reports,
or demo your new product.  Plus, there are 10-15 million other users who
can reach your services through MCI Mail, Compuserve, and AT&T Easylink
gateways.

Theoretically, this distribution should be straightfoward to install and
use on all UNIX systems.  However, it has been tested mostly on Sun
Workstations. We are very interested to hear of your experiences, both
good and bad.

A Tour Through This Distribution
--------------------------------

As distributed by EIT, the ServiceMail(tm) Toolkit contains a toplevel
Makefile, this README, copyrights and disclaimers in LICENSE, and two
subdirectories, bin and src.  The bin directory contains some toolkit
shellscripts, and when installed, some toolkit binaries.

The src directory contains four subdirectories:

  mesh -- the source for the Multimedia Email SHell.

  services -- TCL code for some sample services and the service
     configuration file.

  tcl -- the basic Berkeley TCL package, in case you don't have it already

  metamail -- pieces of the Bellcore Metamail package


Installation
------------

The first thing you must do is procure an account that is dedicated to
ServiceMail(tm).  We recommend calling it "services", and giving it only
the most basic user priviledges (read/write its home directory, read
and execute standard UNIX commands).  Make sure you give it a good
(read: obscure) password, especially if the account is called "services",
since standard account names are often the subject of system attacks.
This account should be for ServiceMail(tm) only, e.g., don't use your own
account because all email will be redirected to the email shell (though
I suppose you could change the way unrecognized services are handled
by stuffing the messages into your personal mailbox).

In order for mesh to work, the command path must be set in ~/.cshrc (this
is the proper place to set the path, but some systems do this wrong in
their newuser files).  The path should include ~/bin, i.e., there should
be a line like the following in ~/.cshrc:

  set path = (~/bin /usr/local/bin /usr/ucb /usr/bin /bin)

Now, if you have the distribution as servicemail.tar.Z:

  Other than creating the services account, no administrator priviledges
  are required.  Log in as services, make sure you are in ~services and
  the Toolkit .tar.Z file is handy, and unpack it by

    % uncompress servicemail.tar.Z
    % tar xf servicemail.tar

Or, if you have the distribution as servicemail.sh:

  Other than creating the services account, no administrator priviledges
  are required.  Log in as services, make sure you are in ~services and
  the Toolkit .sh file is handy, and unpack it by

    % sh servicemail.sh

Either will create the directory structure described above.  Typing "make"
will install the toolkit and wire it up to email.  Before you do so, you
should consider some installation options.

Installation options
--------------------

Most of the installation customization is done by editing the file in
src/mesh/Makefile.

1. If you don't have the Bellcore Metamail package installed, consider
   getting it because more and more people and Mesh servers will
   be sending you multimedia email!  The package can be retrieved via
   anonymous ftp from thumper.bellcore.com.  Mesh works better if you
   have the metamail program called "splitmail", which the email shell
   uses to fragment large outgoing messages.  However, it is not required;
   if splitmail is not available then change the MAILER variable in
   src/mesh/Makefile to refer to sendmail.  It should be obvious how to
   do so.

2. If you didn't in fact install the distribution in the home directory
   of a dedicated account, you will want to edit all the uses of the
   $(HOME) variable to point somewhere else.

3. If you already have the basic TCL distribution, including its *.h
   files and libtcl.a, you can change the TCLLIBDIR and TCLSRCDIR variables
   to point somewhere else.  You can then remove the src/tcl subdirectory
   to save disk space.

4. If you have a better temporary directory than /tmp, change TEMPDIR

5. Mesh will detect certain errors when running services, and Cc a
   ServiceMail administrator when sending a bug report.  To make this
   work, edit ~/src/mesh/config.tcl and set the "administrator" variable.

6. Upon successful installation, EIT is automatically informed of a
   new ServiceMail site (we treat this as confidential information.
   This is for the purpose of sending out bug reports (security bugs
   in particular) and information about new versions.  If you wish
   anonymity, remove the /usr/ucb/mail command from the Makefile.

When you have adopted or declined these options, type "make" in the
home directory.  The email shell will then be online, with a minimum set
of services; try "help" and "services".  If these work, chances are you
have installed the toolkit successfully.


Configuring Example Services
----------------------------

The toolkit comes with several example services that are almost online.
To actually turn them on, edit the file src/mesh/config.tcl and
"uncomment" out one or more of the "define-service" lines.  Some of
these services are system dependent (latex2ps requires the latex and
dvi2ps commands), and some require some setup (listserv requires the
directory ~/Lists and some existing mailing lists to do much;
archive-request requires the directory ~/archive and some files therein
to manipulate) -- check the comments and code for these services.


Creating Custom Services
------------------------

The main reason to use this toolkit is to build custom services.  One of
these days we'll have a graphical and/or interactive interface for building
new services, but for now there's no getting around a little hacking.  If
you are not familiar with TCL, it helps to have some experience in writing
UNIX shell scripts.  We recommend that you start with one of the example
services in src/services.  There is a lengthy man page on TCL in
src/tcl/doc/Tcl.man.  Also, look at src/services/README for some information
on special TCL builtins and calling conventions.

A word about security.  If you build an "exec" service, you are asking for
trouble.  There are also many subtle ways to create security problems.
For example, if any of your services evaluate their switches, then someone
can send "{rm -r *}" as a switch and cause problems.  Make sure that
publicly available services don't consume substantial resources; e.g.,
if any service prints output (or mills parts!) make sure it is obscure or
has some access control.  The example ps2paper service uses a simple
scheme to check if requestors are local; it's better than nothing but
fairly easy to fool.

We want to hear from you!
-------------------------

Please let us know when you install the toolkit and what kind of services
you are building for public use.  We are working on a directory
service that will help people find public services and discover how to
invoke them.  When you install a new, public service, send a message to
the "register" service at "services@eitech.com", with a description of
your service in the body (for now, in any format you wish).  To see
what public services others have produced, try the "directory" service.

If you have problems, questions or suggestions write a message to the
"servicemail-help@eitech.com" mailing list.  You can join this mailing
list be sending a message to the
"listserv subscribe servicemail-help your-real-name" service at
"services@eitech.com".

IF YOU WANT FUTURE UPDATES ON TOOL KIT VERSIONS, BUGS, AND SERVICES,
MAKE SURE YOU ARE ON THE PACT-KIT MAILING LIST.  To get on it, send
a message to "services@eitech.com" with subject
"listserv subscribe pact-kit your-real-name".

(* This work was supported in part by DARPA prime contract
   DAAA15-19-C-0104 through Lockheed subcontract SQ70A3030R,
   monitored by the U.S. Army Ballistic Research Laboratory;
   this work was also funded in part by DARPA under a subcontract
   from Stanford University on contract N-00014-90-J-4016 )
