USAGE

Important Note For Users Upgrading From Earlier Versions
--------------------------------------------------------

SpamAssassin no longer includes code to handle local mail delivery, as it
was not reliable enough, compared to procmail.  So now, if you relied on
spamassassin to write the mail into your mail folder, you'll have to
change your setup to use procmail as detailed below.

If you used spamassassin to filter your mail and then something else wrote
it into a folder for you, then you should be fine.

Steps to take for every installation:

  - Install Mail::SpamAssassin on your mail server, as per the INSTALL
    document.

  - Test it:

      spamassassin -t < sample-nonspam.txt > nonspam.out
      spamassassin -t < sample-spam.txt > spam.out

    Verify (using a text viewer, ie. "less" or "notepad") that nonspam.out
    has not been tagged as spam, and that spam.out has.  The files should
    contain the full text and headers of the messages, the "spam.out"
    message should contain the header "X-Spam-Flag: YES" and be annotated
    with a report from SpamAssassin, and there should be no errors when you
    run the commands.

    Even though sample-nonspam.txt is not spam, nonspam.out will contain a
    SpamAssassin report anyway.  This is a side-effect of the "-t" (test)
    switch.  However, there should be less than 5 hits accumulated; when
    the "-t" switch is not in use, the report text would not be added.

    If the commands do not work, DO NOT PROCEED TO THE NEXT STEP, as you
    will lose mail!



If you use Mail::Audit already:

  - run "perldoc Mail::SpamAssassin" and take a look at the synopsis, it
    outlines what you need to add to your audit script.

  - Copy the configuration files (see CUSTOMISING, below) to a known
    location, so your script can set the appropriate options for the
    Mail::SpamAssassin constructor to load them.



If you use KMail:

  - http://kmail.kde.org/tools.html mentions:

    The filter setup is the work of five minutes (if that!) if you have a
    working spamassassin set up.

    The filter in question is "<any header><matches regexp> ."

    The action is "<pipe through> spamassassin"

    Then, in the advanced options, uncheck the "If this filter matches,
    stop processing here" box. If you keep this filter at the top, it will
    analyze any incoming mail, decide whether it's spam or not, and flag
    it accordingly.

    [Then add] a second filter behind it, which searches for the added
    spam-flags and diverts them into a specific spam folder. [...]



If you use procmail, or haven't decided on any of the above examples:

  - Make a backup of your .procmailrc (if you already have one).

      cp ~/.procmailrc ~/.procmailrc.bak

  - add the line from procmailrc.example to ~/.procmailrc, at the top of
    the file before any existing recipes.

    That'll process all mail through SA, and refile spam messages to
    a folder called "caughtspam" in your home directory.

  - Send yourself a mail message, and ensure it gets to you.  If it does
    not, copy your old backed-up .procmailrc file back into place and ask
    your sysadmin for help!  Here's commands to do that:

      cp ~/.procmailrc.bak ~/.procmailrc
      echo "Help!" | mail root



If you want to use SpamAssassin site-wide:

  - take a look at the notes on the website, at
    http://spamassassin.org/sitewide.html .  You will probably want to use
    'spamd' (see below).

  - *PLEASE* let your users know you've installed it, and how to turn it
    off!   This is our #1 tech support query, and the users are usually
    pretty frustrated once it reaches that stage.

  - *PLEASE* consider setting it up as "off by default" for most accounts,
    and let users opt-in to using it.  Quite a few folks prefer not to
    have their mail filtered, presumably because they don't use their
    email address publically and do not get much spam.

  - Note that procmail users adding spamc to /etc/procmailrc should 
    add the line 'DROPPRIVS=yes' at the top of the file.


The Auto-Whitelist
------------------

The auto-whitelist is enabled using the -a flag to spamassassin or spamd.  

The algorithm works using a database of entries. Each entry has a key formed by
the From: address of the mail, and the IP address it originated at, and
contains a TOTAL score and a COUNT number. The MEAN score is TOTAL/COUNT. The
current algorithm works as follows:

   1. Compute the SCORE of the message without AWL (auto-whitelist)
   2. Compute AWL DELTA as (MEAN-SCORE)*auto_whitelist_factor
   3. Increment TOTAL by SCORE
   4. Increment COUNT by one
   5. Set the final score of the message to SCORE+DELTA

auto_whitelist_factor can be tweaked in the configuration, and you
may find this useful when starting off.  The contents of the database
can be examined using the program 'tools/check_whitelist'.


Other Installation Notes
------------------------


  - SpamAssassin now uses a temporary file in /tmp (or $TMPDIR, if that's
    set in the environment) for Pyzor and DCC checks.  Make sure that this
    directory is either (a) not writable by other users, or (b) not shared
    over NFS, for security.


  - You can create your own system-wide rules files in
    /etc/mail/spamassassin; their filenames should end in ".cf".  Multiple
    files will be read, and SpamAssassin will not overwrite these files
    when installing a new version.


  - You should not modify the files in /usr/share/spamassassin; these
    will be overwritten when you upgrade.  Any changes you make in
    files in the /etc/mail/spamassassin directory,  however, will
    override these files.


  - Rules can be turned off by setting their scores to 0 in a
    configuration or user-preference file.


  - Speakers of Chinese, Japanese, Korean or Arabic may find it useful to
    turn off the rules listed at the end of the "user_prefs.template"
    file; we've found out that these rules are still triggering on
    non-spam CJK mails.


  - If you have an unusual network configuration, you should probably
    set 'trusted_networks'.  This allows SpamAssassin to determine where
    your internal network ends and the internet begins, and allows DNS
    checks to be more accurate.


  - MDaemon users should add this line to their "local.cf" file:

      report_safe_copy_headers X-MDRcpt-To X-MDRemoteIP X-MDaemon-Deliver-To


  - The distribution includes 'spamd', a daemonized version of the
    perl script, and 'spamc', a low-overhead C client for this,
    contributed by Craig R. Hughes.  This greatly reduces the overhead of
    checking large volumes of mail with SpamAssassin.  Take a look in the
    'spamd' directory for more details.


  - spamc can now be built as a shared library for use with milters or
    to link into other existing programs; simply run "make libspamc.so"
    to build this.


  - If you get spammed, it is helpful to everyone else if you re-run
    spamassassin with the "-r" option to report the message in question as
    "verified spam".  This will add it to Vipul's Razor
    (http://razor.sourceforge.net/), a collaborative spam filtering
    network, if you've installed the Razor modules and registered an
    account.

      spamassassin -r < spam-message

    If you use mutt as your mail reader, this macro will bind the X key to
    report a spam message.

      macro index X "| spamassassin -r"

    This is, of course, optional -- but you'll get lots of good-netizen
    karma. ;)


  - Quite often, if you've been on the internet for a while, you'll have
    accumulated a few old email accounts that nowadays get nothing but
    spam.  You can set these up as spam traps using SpamAssassin; see the
    ''SPAM TRAPPING'' section of the spamassassin manual page for details.

    If you don't want to go to the bother of setting up a system yourself
    to do this, feel free to set up a simple alias to forward any mails to
    <someaddress@spamtraps.taint.org> -- replace "someaddress" with
    something to identify you, such as your email addr or website with
    non-alphanumeric chars replaced by underscores, or similar.  (Please
    also send me a mail at jm - spamtraps at jmason dot org if you do
    this, so that I know who to contact if it starts going haywire, or the
    quality drops.)
    
    Mails sent to an address at the spamtraps domain are fed into the
    SpamAssassin.org spam-trapping system, where they will then be
    virus-scanned, de-duplicated, and fed into Razor, DCC, Pyzor and OPM.

    Some notes: I monitor the quality of feeds coming into this, and if it
    turns out to contain occasional bits of non-spam mail, I'll start
    bouncing your feed with a 550 -- as a spam feed that isn't reliably
    spam-only is *not* suitable for a spamtrap.
    
    Also, messages relayed to the spamtrap must be either (a) direct
    relaying as performed by a sendmail alias, or (b) message/rfc822
    attachments with no Content-Transfer-Encoding.  Again, if they're not,
    I'll 550 them.  And finally, if I can't figure out who's in control of
    the feed, you guessed it, 550.  So try to keep the quality control
    up!


  - Scores and other user preferences can now be loaded from an SQL
    database; see the 'sql' subdirectory for more details.


  - Edward Fang <edfang /at/ visi.net> has contributed the
    'communigate.sh' script for CommunigatePro (see the 'contrib'
    directory).


  - James Henstridge <james /at/ daa.com.au> has contributed an LMTP proxy
    server (designed for Cyrus, but probably will work fine with others),
    again it's in the contrib directory.


  - Lots more ways to integrate SpamAssassin can be read at
    http://news.SpamAssassin.org/ .


(end of USAGE)

// vim:tw=74: