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:

    (p * c) ^ 2 * sign(p) * MaxWeight

  where sign(p) is -1 if p < 0, and +1 otherwise, and MaxWeight is
  specified on a configuration line.  MaxWeight is greater than or
  equal to zero.

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_OR_NO

where NN specifies the SNFServer result, and S is the SpamAssassin
score for that SNFServer result.  YES_OR_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_OR_NO" is optional, and the default value for
YES_OR_NO is "no" (which specifies that SpamAssasin continue
scanning).

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.