
                        Mark's Mailbot Version 0.1
			===========================

Mailbot is a program intended for use by technomads and others who may 
wish to maintain a Web site via email. The current version is very much 
an alpha-test, though I will be relying on it while I travel. It has 
only been tested on SunOS 4.1.x but should be fairly portable. It compiles 
on Linux but has not been tested. The facilities it provides are as follows:

   * Seperating messages into multiple mailboxes.
   * Updating Web pages via email.
   * Retrieving Web pages via email.
   * Retrieving files via email.
   * Creation of one-way mailing lists.
   * Accepting emailed updates on your progress, automatically forwarding
     them to mailing list subscribers and converting them to HTML to add to
     your Web pages.

In order to use the mailbot you must be able to map multiple email addressed
onto your individual address. For example, you must be able to take email
for www@foo.com and me@foo.com and pass both to your email account
me@foo.com. In order to do this you will probably need either the
cooperation of the system administrator on your ISP, or to register your own
domain name.

Your .forward file should be set up to pass all incoming mail to the mail-in
script. This will save each message in a seperate file in the $HOME/in
directory. Mailbot should then be run regularly from cron, typically every
ten minutes. It will scan all the files in $HOME/in and process the messages
as appropriate.

You must edit the defs.c file to specify the action to take for mail to each
email address. In this file is an array called 'procs' which tells the code
what it should do. Here is an example.

PROC procs[] =
{
        { "mark", save_message, MAIL_FILE },
        { "www", maybe_save_message, "www" },
        { "postmaster", maybe_save_message, "postmaster" },
        { "bot", send_file, "data/bot.txt" },
        { "help", send_file, "data/bot.txt" },
        { "latest", send_file, "data/latest.txt" },
        { "update-list", process_update_list, "data/update/update.lst" },
        { "update-list-owner", maybe_save_message, "postmaster" },
        { "pgp-keys", send_file, "data/keys.asc" },
        { "null", junk_message, 0 },
        { "/dev/null", junk_message, 0 },
        { "nobody", junk_message, 0 },
        { "html", send_html, 0 },
        { "update", process_update, "data/update/update.lst" },
        { "www-update", process_www_update, 0 },
        { 0, 0, 0 },
};

As you can see, each line has three elements. The first element is the email
address. The second element is the procedure to call when mail to that email
address is receiveed. The final element is arbitary data to pass to that
procedure. For example, if your domain name is foo.com and mail is received
for www@foo.com, then the code will call 'maybe_save_message()' and pass the
string "www" to that procedure.

These routines are defined in main.c. The current selection are as follows:

     save_message()
          Saves a message to an arbitrary file. If the filename specified
          starts with a /, then it is taken to be an absolute pathname.
          Otherwise it is taken to be relative to $HOME/mail.
     maybe_save_message()
          This function acts as save_message() but it will only save the
          message if the file is smaller than a defined limit. This is
          currently set to 64k. If the message is too large, then it will be
          bounced back to the sender.
     send_file()
          Returns an arbitrary file to the sender of the email. If the
          filename starts with a / it is taken to be an absolute pathname,
          otherwise it is taken to be relative to $HOME.
     junk_message()
          Simply throws away the received message.
     process_update_list()
          This function allows users to subscribe and unsubscribe from your
          mailing lists. The subscriber list will be stored in the specified
          file, as usual either an absolute path or relative to $HOME.
     process_update()
          This function takes an incoming message and verifies the PGP
          signature. If the signature fails then the message will be bounced
          back to the sender, otherwise it converts the text to HTML and
          saves it in a file in your HTML tree. It will then update an
          arbitrary database file so that your CGI script can list the
          available files and allow browsers to view them. Finally it will
          forward a copy of the message to each of the subscribers on the
          mailing list. If the email address specified for this procedure is
          foo, then the mailing list address must be foo-list and the data
          files stored in $HOME/data/foo.
     send_html()
          This function checks the subject line for a URL and if found will
          mail back the specified file. GIF, JPEG and MPEG files will be
          uuencoded before they are sent.

Mail to any address at your domain which is not specified in this file will
be bounced. If the mailbot cannot find an appropriate email address in the
header, then the message will be saved to your default mail file.

Once you have set up the defs.c file appropriately you will need to edit the
Makefile. You need to set the definitions at the beginning of the file.
WWWHOME should be set to the top-level URL of your web site, USERNAME to
your full name, DOMAIN to your email domain, and MAIL_FILE to the location
of your default mail file. For example:

WWWHOME=http://www.c2.org/~mark/
USERNAME=Mark Grant
DOMAIN=unicorn.com
MAIL_FILE=/usr/spool/mail/mark

You will also need either a copy of PGP and possibly PGP Tools if you wish
to use the remote update features.

The Mailbot Web page is at http://www.c2.org/~mark/mailbot/.

List_updates
============

The list_updates CGI script will give the user a list of all the updates you
have mailed in, and allow them to view the files. You must create start.dat
and end.dat files which will be prepended and appended to the list of
updates. You may also create an itinerary.dat file containing your itinerary
and this will be included in the middle of the Web page. Seperating the
files this way allows you to maintain them more easily.

You may wish to look at my installation to see it working for real. The
script works on SunOS and FreeBSD and compiles on Linux. The script is
running on the Web at http://www.c2.org/mark-cgi/list_updates. 

