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
    points accumulated; when the "-t" switch is not in use, the report
    text would not be added. For more verbose (debugging) output, add
    the "-D" switch.

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



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 Wiki website, currently at
    <https://wiki.apache.org/spamassassin/UsingSiteWide>.  You will probably
    want to use 'spamd' (see below).   You may want to investigate the
    new Apache mod_perl module, in the 'spamd-apache2' directory, too.

  - *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 publicly 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-Welcomelist
------------------

The auto-welcomelist is enabled using the 'use_auto_welcomelist' option.
(See https://wiki.apache.org/spamassassin/AutoWelcomelist for details on
how it works, if you're curious.)


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. If your mail host is NATed, you will
    almost certainly need to set 'trusted_networks' to get correct
    results.


  - A very handy new feature is SPF support, which allows you to check
    that the message sender is permitted by their domain to send from the
    IP address used.  This has the potential to greatly cut down on mail
    forgery.


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

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

    Otherwise, MDaemon's internal delivery will fail when SpamAssassin
    rewrites a message as spam.


  - The distribution includes 'spamd', a daemonized version of
    SpamAssassin which runs persistently.  Using its counterpart,
    'spamc', a lightweight client written in C, an MTA can process
    large volumes of mail through SpamAssassin without having to
    fork/exec a perl interpreter for each message. Take a look in the
    'spamd' and 'spamc' directories for more details.


  - The distribution also includes 'spamd-apache2', a mod_perl module
    allowing the Apache HTTP server to be used as a platform for a
    daemonized SpamAssassin, in an upwardly-compatible fashion from
    'spamd'.  If you don't require some of the spamd features it does not
    implement (such as switching UIDs to read per-user configuration from
    user home directories), this may be much faster than spamd.  Take a
    look at the 'spamd-apache2' directory for 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, DCC and Pyzor,
    assuming you've set these up appropriately.

      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, take a look here [1] for a simple forwarding-based
    alternative.

      [1]: https://wiki.apache.org/spamassassin/SpamTrapping


  - Scores and other user preferences can now be loaded from, and Bayes
    and automatic reputation data can be stored in, an SQL database; see
    the 'sql' subdirectory for more details.

    If you are setting up a large 'spamd' system-wide installation, with
    Bayes and/or automatic reputation, we strongly recommend using SQL as
    storage.  It has proven more reliable than the default DB_File storage
    backend at several large sites.  For Bayes, you should always use the
    new Redis backend (see Mail::SpamAssassin::BayesStore::Redis).


  - If you are running SpamAssassin under a disk quota, or are setting up
    'spamd' with users with disk quotas, be warned that the DB_File
    database module used by SpamAssassin for Bayes, TxRep, and AWL storage
    seems to be unreliable in the face of quotas (bug 3796). In this
    situation, we recommend using SQL storage for those databases, instead
    of DB_File.


  - Lots more ways to integrate SpamAssassin can be read at
    https://wiki.apache.org/spamassassin/ .


(end of USAGE)

// vim:tw=74: