		 Spam: a companion tool to Mailfilter
	(C) 2002 Franck Pommereau <pommereau@univ-paris12.fr>

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation; either version 2 of the
    License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    02111-1307 USA


INTRODUCTION
============

Spam is a Perl script which should help in removing unsolicited mails
(spams). It parses mails and produces rules suitable to Mailfilter,
which makes it possible to remove them from your POP server. Spam will
not do everything for you but it will help to quickly update your
Mailfilter configuration.


INSTALLATION
============

Spam needs the following to be installed:

  - the scripting language Perl
  - the Perl package Getopt::Long
  - several Unix utilities: "vi", "savelog", "date", "mkdir" and
    "touch"

Then, you need to copy the script "spam" in a location from where is
can be executed (somewhere in your PATH), and finally, you just need
to run "spam --install" which will install all required files and
directory. In particular, it updates your file "~/.mailfilterrc" which
should be correctly configured in order to run Mailfilter. You may
also run something like "spam -A ~/Mail/*" (see option -A below) in
order to create the list of people which you don't consider as
spammers (except if you use to save spams instead of just deleting
them).

In order to uninstall Spam, run "spam --noinstall" and then delete the
script "spam".


USAGE
=====

(In the following we assume that the reader is quite familiar with
Mailfilter and regular expressions.)

When you receive mails that you don't want to see anymore, simply pipe
them through "spam". If you mailer does not support pipes, you may
save the unwanted mails in a file, say "spambox", and then run "spam
spambox". WARNING: Do not run "spam -A spambox" (or something
equivalent, for instance "spam -A ~/Mail/*" if "spambox" is in the
directory "~/Mail") otherwise you would explicitly allow mails from
the spammers in "spambox".

Spam will create rules allowing Mailfilter to delete these junk mails
the next time they will arrive. Rules are created into two files:

  "~/.spam/allow"   for ALLOW rules (only updated by "spam -A")
  "~/.spam/deny"    for DENY rules (the most often updated)

Both files are included from "~/.mailfilterrc" which so can be kept
human readable and is never changed by Spam (except during an
install/uninstall).

Various options allow for controlling how the rules are created. Most
have a short and a long version. Spam supports options concatenation,
for instance, "-fm" is equivalent to "-f -m".

  -f, --from
  -m, --mailer
  -s, --subject
  -t, --to
  Create rules by collecting headers "From", "X-Mailer", "Subject" or
  "To" respectively.  (If none of these option is used, -s is
  assumed.) The created rules are displayed.

  -a, --all
  Shorthand for "-f -m -s -t".

  --head=HEADER
  Create rules using the given header.

  -x, --exact
  Force Spam to build rules exactly matching the headers. See EXACT
  MATCHING below for explanations.

  -q, --quiet
  Do not issue messages about what is being proceeded.

  -e, --edit
  "spam -e" is exactly the same as "vi ~/.spam/deny" so you can edit
  the DENY rules created by Spam.

  -c, --check
  Check if there exists inconsistencies between "~/.spam/allow" and
  "~/.spam/deny"; any address found is both files is reported so you
  can fix the problem.

  -n, --no-write
  Perform a test run, without changing, creating or deleting any file
  or directory.

  -l, --log
  Read "~/.spam/log/mailfilter.log" where Mailfilter is said to
  report what it does. If some information about deleted mails is
  found, it is displayed (in a quite messy form, but usable). This
  allows for checking if something was wrong. Then, the log file is
  rotated using "savelog", except if you used option -n.

  -A, --allow
  Reads files from the command line (or the standard input) and puts
  ALLOW rules for all the encountered "From" headers into
  "~/.spam/allow". Typically, you may run "spam -A ~/Mail/*" before to
  start using Spam. This will create the list of all the people from
  which you store mail and so, from which you explicitly want to allow
  mail.

  --install
  Create files and directories needed by Spam and update
  "~/.mailfilterrc" so Mailfilter can use the rules created by Spam.

  --uninstall
  Undo what --install did.

  -h, --help
  Print a summary of options and exit.

Notice that when using one of options --install, -l, -A or -e, Spam
won't have its usual behaviour and won't create any rule. Moreover,
when using both -n and -q, the only possible visible action of Spam is
to report an error if its files (located under "~/.spam") are not
found.


EXACT MATCHING
==============

By default, rules created by Spam do not exactly match the headers
found but are more general. The following is a list of these
generalisations, each applies to one or several headers listed before
the explanation. After each rule, we give examples of actually read
headers (marked "=") followed by headers which will be also matched
thanks to the generalisation (marked ">"). All these generalisations
come from observed spammers methods.

  Subject:
  Trailers made with several spaces followed by random letters are
  removed.
  = Subject: Rates at an All-time Low.         fdzpio
  > Subject: Rates at an All-time Low.         hgsfjh
  > Subject: Rates at an All-time Low.       kjgfjhgkjh

  Subject:
  Characters others than numbers, letters, spaces and ":" are replaced
  by the regexp ".*" which matches any sequence of characters.
  = Subject: Women Agree "Size DOES Matter" So GO BIG Now!
  > Subject: Women Agree ``Size DOES Matter'' So GO BIG Now!
  > Subject: Women Agree "Size DOES Matter" So GO BIG Now!!!

  Subject, From:
  Numbers are replaced by the regexp ".*" which matches any string. In
  email addresses, everything after the first number and until the "@"
  is replaced by ".*".
  = From: morthelp01238975u91008@yahoo.com
  > From: morthelp012389444x29p3@yahoo.com
  = Subject: New Pill Adds 1 to 3 inchs to your ...
  > Subject: New Pill Adds 2 to 5 inchs to your ...

  Subject:
  Several spaces are replaced by the regexp ".*".
  = Subject: Re:  Free sign up for money!
  > Subject: Re: Free sign up for money!
  > Subject: Re:   Free sign up for money!

  From:
  Only the actual mail address is matched.
  = From: "Mandy Tweed" <mandy24k@hotmail.com>
  > From: "Mandy Steed" <mandy24k@hotmail.com>
