PKG-SNF-CS-NIX/SNF_CS_Developer_Package/SNF4SA/INSTALL

               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.

The plugin uses the SNFServer results to calculate a plugin score.
For SpamAssassin with a version of 3.2.0 or later, this plugin score
is added to the SpamAssassin score for the message.

If the SpamAssassin version is earlier than 3.2.0, then the plugin
compares the plugin score to plugin score threshold.  If the plugin
score is greater than or equal to the plugin score threshold, then a
static score is added to the SpamAssassin score for the message.  Both
the plugin score threshold and static score are specified in the
configuration file.

Plugin Configuration 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 plugin 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 plugin 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 plugin score.

  4) The plugin score threshold and static score (used only if the
  SpamAssassin version is earlier than 3.2.0).

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
plugin 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 plugin 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 plugin 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 plugin 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 plugin score.  SpamAssassin
continues to process the email.

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

The following line specifies the MaxWeight parameter:

  GBUdb_max_weight MaxWeight

where MaxWeight is the value to specified.  For example,

  GBUdb_max_weight 3.0

specifies a MaxWeight value of 3.0.

For SpamAssassin with version earlier than 3.2.0
------------------------------------------------

The following line specifies the plugin score threshold:

  pre_3.2_plugin_score_threshold Threshold

where Threshold is the value to specified.  For example:

  pre_3.2_plugin_score_threshold 1.1

causes the static score to be added if the plugin score is equal to or
greater than 1.1.

The following line specifies the static score:

  score SNF4SA Score

where Score is the static score to add to the SpamAssassin score for
the message.  For example:

  score SNF4SA 8.0

specifies a static score of 8.0.  If the SpamAssassin version is
earlier than 3.2.0, and the plugin score is equal to or greater than
the plugin score threshold, then a value of 8.0 would be added to the
SpamAssassin score for the message.

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