                         Mark's Mailbot Version 0.12
			 ===========================

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.
   * Auto-bouncing spam.
   * Creation of two-way mailing lists.
   * Anonymous remailer support.

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" },
        { "wwwupdate", 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.
     scan_and_save_message()
          First does a spam-check, then either bounces the message back to
          the spammer or saves it in the indicated file.
     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.
     process_mailing_list ()
          This function processes subscribe and unsubscribe messages for
          two-way mailing lists.
     mailing_list()
          This function processes messages sent to a mailing list.
     spam_checked_mailing_list()
          This function processes mailing list messages after first passing
          them through the spam filter.
     save_for_remailing()
          This function can be used to interoperate with the mail reordering
          code if you're running an anonymous remailer on your account. It
          copies the messages into the remailer input directory, taking care
          to avoid race conditions.

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.

Several arrays in the defs.c file allow you to bounce or delete spam. They
are as follows:

     spampath[]
          Any message forwarded via a site in this list may be bounced. Note
          that the code simply looks for this string, and any supersets.
          Hence "foo.com" would bounce mail from "bar.foo.com" and
          "fred.foo.com".
     spamsites[]
          Any message whose From: field contains a string in this list may
          be bounced.
     spamto[]
          Any message whose To: field contains a string in this list may be
          bounced.
     spamid[]
          Any message whose Message-Id: field contains a string in this list
          may be bounced.
     spammailer[]
          Any message whose Mailer: or X-Mailer field contains a string in
          this list may be bounced.
     spamcontents[]
          Any message whose body contains more than a defined number of
          strings in this list may be bounced. We also check the body for
          strings in the spamsites[] and spampath[] array and include them
          in the total.
     alwayspass[]
          Any message whose From: field contains a string in this list will
          always be passed, regardless of any other indications of spam.
          This allows you to block all mail from an ISP yet allow some As
          for alwayspass[], but uses the To: field instead.
     neverbounce[]
          Mail will never be bounced to an address in this list, but will
          simply be thrown away. This is intended to prevent accidental
          spamming of mailing lists by the mailbot. If you include the
          addresses of any mailing lists you are subscribed to in this list
          then if spam is posted to the list the mailbot will simply junk it
          rather than bounce it back to the list and thence to every
          subscriber.
     spamheader[]
          Any message containing this string in the header may be bounced.
     spamsubject[]
          Any message containing these strings in the subject may be
          bounced.
     deletefrom[]
          Any message from one of these addresses will be deleted
          automatically.

For each message, these rules are applied and we count the number of
failures, biased by the 'severity' of the failure. If the 'spam count' is
above MAYBE_SPAM (currently set to 3), then by default the message will be
saved to the spam folder, or if it is above DELETE_THRESHOLD it will be
deleted. Alternatively, by defining BOUNCE_SPAM when compiling, any
suspicious messages will be bounced. I don't recommend this procedure as
most spam has a fake return address. Finally, if you don't define
NO_WEB_LIST, then a file will be created in
$HOME/public_html/spam-caught.html to list all messages which the
spam-filter thinks are at least 75% likely to be spam. This allows you to
keep track of who's been spamming you while you're out on the road.

Compiling

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.unicorn.com/~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.

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.

----------------------------------------------------------------------------

Where to find Mailbot

The Mailbot code is covered by the US crypto-export regulations, making it
illegal to export from the US. Since I'm in Europe at the moment the code is
available world-wide in any case; you should be able to find it on
utopia.hacktic.nl.

For more information see http://www.unicorn.com/mailbot.

