SpamAssassin SNF4SA Plugin for SNFServer
                    Installation and Configuration

              Copyright (C) 2009 ARM Research Labs, LLC.

           See www.armresearch.com for the copyright terms.
                                   
Installing SpamAssassin SNF4SA plugin for SNFServer involves the
following steps:

  1) Copy snf4sa.pm and snf4sa.cf to /etc/mail/spamassassin .

  2) Edit /etc/mail/spamassassin/snf4sa.cf plugin configuration file
  to meet your needs.  See below for a description of the
  configuration settings.

The module writes the email message to a temporary file in
/tmp/snf4sa.  If this directory doesn't exist, the script creates it
with permission 777.  This allows both the script and SNFServer to
write to that directory.  If that directory already exists, ensure
that it has a permission of 777.

Plugin Configuation Settings
----------------------------

The plugin file (snf4sa.cf) contains required lines that:

  1) Configures SpamAssassin to load the plugin.

  2) Describes the plugin.

  3) Configures SpamAssassin to add the X-Spam-SNF-Result header to
  the email.  This header contains the results of the SNF scan.

In addition, there are lines that can be configured by the user that
specifies:

  1) Which emails to process through SNFServer.

  2) The relationship between SNFServer results and the SpamAssassin
  score.  You can specify the value added to or subtracted from the
  SpamAssasin score for each SNFServer result.  You can also specify
  whether SpamAssasin should abort further processing for eacn
  SNFServer result.

  3) The relationship between the GBUdb results and the SpamAssassin
  score.  The GBUdb probability p and confidence c add the following
  value to the SpamAssasin score:

    abs(p * c) ^ 0.5 * sign(p) * MaxWeight

  where sign(p) is -1 if p < 0, and +1 otherwise, and MaxWeight is
  specified in a configuration line.  MaxWeight is greater than or
  equal to zero.  If MaxWeight isn't specified in the configuration
  file, then the GBUdb results don't affect the SpamAssassin score.

To specify which emails to process, use a line similar to:

  full SNF4SA eval:snf4sa_sacheck()

The above line specifies that all emails be processed.  Please see the
SpamAssassin documentation for other options.

To specify the relationship between the SNFServer results and the
SpamAssassin score, enter zero or more lines with the format:

  snf_result NN sa_score S short_circuit_[yes|no]

where NN specifies the SNFServer result, and S is the SpamAssassin
score for that SNFServer result.  [yes|no] is "yes" if further
scanning should be skipped if SNFServer returns the result specified
by NN, or "no" if further scanning should not be skipped.  NN can be a
combination of a series of one or more integers, and a range of
integers specified by N-M, where N and M are integers.  The
"short_circuit_[yes|no]" is optional, and the default value for
[yes|no] is "no" (which specifies that SpamAssasin continue scanning).

NOTE: There must not be any space when specifying a range of integers.
For example, specify "34-43" rather than the incorrect "34 - 43".

For example:

  snf_result 63 sa_score 2.5 short_circuit_no

causes the plugin to add 2.5 to the SpamAssassin score if SNFServer
returns 63 (which in the default SNFServer configuration corresponds
to "caution").

Another example:

  snf_result 45 47-62 sa_score 5.0 short_circuit_yes

causes the plugin to add 5.0 to the SpamAssassin score and stop
further processing if SNFServer returns 45 or 47 thru 62.

Final example:

  snf_result 1 sa_score -5.0

causes the plugin to subtract 5.0 from the SpamAssassin score.
SpamAssassin continues to process the email.

If SNFServer returns a result that isn't specified, then the plugin
adds zero to the SpamAssassin score.

The following line specifies the MaxWeight parameter:

  GBUdb_max_weight MaxWeight

where MaxWeight is the value to specify.  For example,

  GBUdb_max_weight 3.0

specifies a MaxWeight value of 3.0.

Debugging the configuration
---------------------------

The configuration can be tested by running

    spamassassin --lint

This outputs a message if any line in in the configuration file cannot
be parsed, along with the offending line.

In order to obtain more detailed information, run

   spamassassin -D --lint

This command outputs information about why a line could not be parsed.
The output includes a great deal of other debugging information; you
can filter the information relevant to this plugin like this:

   spamassassin -D --lint 2>&1 | grep snf4sa