Spamkiller package
==================
This package is released under the GPL. It is the copyright property of
Martin Gregorie, 2009

The package contains spamkiller, a program that deletes mail that has 
been marked as spam. This is designed to be placed downstream of 
Spamassassin or spamc in a pipeline. It checks the X-Spam-Flag header
to determine whether a message has been marked as spam:

- Messages marked as spam are discarded by default but can optionally
  be saved as separate files in a directory, which defaults to
  'quarantined' in the current working directory.
- Messages not marked as spam are delivered to the MTA using the 
  configured command.

NOTE: Spamkiller has been tested as part of the mda script used by both
      fetchmail and getmail. This script calls spamc and spamkiller, which 
      sends non-spam to Postfix by calling the sendmail utility program. 
      By default spam is silently discarded but, if the -s option is present
      spam is written to a quarantine directory as separate files whose
      names take the form of a modified ISO 8601 timestamp 
      (yyyy-mm-dd_hh:mm:ss with a letter suffix added to prevent duplication).
      The directory name defaults to 'quarantined' in spamkiller's current
      working directory, normally the root directory of the user where 
      spamkiller is run but this can be overridden by adding a value to the 
      -s option, e.g. "-s=dirpathname".

      There is no reason why spamkiller can't be used to:

      - vet incoming mail for any other MTA. The MTA must provide a 
        suitable utility that spamkiller will use to transmit nonspam
        mail to the MTA.

      - as a Postfix message processing service.

      but these uses have not been tested.

The package also contains a number of scripts:
- skdiscards - a logwatch addin that reports spam discarded by spamkiller
- skerrors   - a logwatch addin that reports any errors logged by spamkiller.
- spamclean  - a bash script to delete old spam from the quarantines directory.
               It is designed to run as a cron job and should be put in 
               /etc/cron.daily
- qis.php    - a PHP script used to examine quarantined spam.
               It should be put in the public_html directory of the user
               where spamkiller runs and made accesible to a local webserver.
               It has been tested with Apache 2.4.

Compilation
===========
1. Download, compile and install my environ package, which is needed to
   compile spamkiller.

2. Run 'make all' to compile spamkiller.

3. Check that the places Makefile installs executables and other
   files suits your installation.  As issued, it:

   - copies spamkiller to /usr/local/bin and its manpage to
     /usr/local/man/man1

   - incorporates the skdiscards and skerrors scripts and their logwatch 
     configurations into your logwatch set-up

   - installs spamclean into /etc/cron.daily

   - adds public_html and quarantined directories to /home/getmail, which
     is the default home directory for getmail, and installs qis.php in
     ~getmail/public_html

4. Run 'sudo make install' to do the installation. This installs the 
   spamkiller program, its manpage and the various scripts.

5. Configure your mail system to use spamkiller to permanently
   delete or quarantine spam.

Using spamkiller
================
This program should be run in a pipeline immediately after spamc or 
Spamassassin. If a message was marked as spam it is discarded. If it
is not spam it spawns a copy of the configured transfer command and
pipes the message into it for transfer to the MTA. The action taken 
by spamkiller is logged in the mail log.

The file dot.fetchmailrc and postfixfilter are provided as templates for
using SA and spamkiller as incoming mail preprocessors. They should also 
be helpful when using it in other MTA configurations.

Contact
=======
Contact me, Martin Gregorie via e-mail as <martin@gregorie.org> to report
problems or for assistance in configuring and using these tools.
