You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by jm...@apache.org on 2006/10/16 17:57:59 UTC
svn commit: r464529 [6/11] - in /spamassassin/site/full/3.1.x: ./ doc/
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PerMsgStatus.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PerMsgStatus.txt?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PerMsgStatus.txt (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PerMsgStatus.txt Mon Oct 16 08:57:50 2006
@@ -0,0 +1,301 @@
+NAME
+ Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)
+
+SYNOPSIS
+ my $spamtest = new Mail::SpamAssassin ({
+ 'rules_filename' => '/etc/spamassassin.rules',
+ 'userprefs_filename' => $ENV{HOME}.'/.spamassassin/user_prefs'
+ });
+ my $mail = $spamtest->parse();
+
+ my $status = $spamtest->check ($mail);
+
+ my $rewritten_mail;
+ if ($status->is_spam()) {
+ $rewritten_mail = $status->rewrite_mail ();
+ }
+ ...
+
+DESCRIPTION
+ The Mail::SpamAssassin "check()" method returns an object of this class.
+ This object encapsulates all the per-message state.
+
+METHODS
+ $status->check ()
+ Runs the SpamAssassin rules against the message pointed to by the
+ object.
+
+ $status->learn()
+ After a mail message has been checked, this method can be called. If
+ the score is outside a certain range around the threshold, ie. if
+ the message is judged more-or-less definitely spam or definitely
+ non-spam, it will be fed into SpamAssassin's learning systems
+ (currently the naive Bayesian classifier), so that future similar
+ mails will be caught.
+
+ $score = $status->get_autolearn_points()
+ Return the message's score as computed for auto-learning. Certain
+ tests are ignored:
+
+ - rules with tflags set to 'learn' (the Bayesian rules)
+
+ - rules with tflags set to 'userconf' (user white/black-listing rules, etc)
+
+ - rules with tflags set to 'noautolearn'
+
+ Also note that auto-learning occurs using scores from either
+ scoreset 0 or 1, depending on what scoreset is used during message
+ check. It is likely that the message check and auto-learn scores
+ will be different.
+
+ $score = $status->get_head_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for header-based ones.
+
+ $score = $status->get_learned_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for learning-based ones.
+
+ $score = $status->get_body_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for body-based ones.
+
+ $isspam = $status->is_spam ()
+ After a mail message has been checked, this method can be called. It
+ will return 1 for mail determined likely to be spam, 0 if it does
+ not seem spam-like.
+
+ $list = $status->get_names_of_tests_hit ()
+ After a mail message has been checked, this method can be called. It
+ will return a comma-separated string, listing all the symbolic test
+ names of the tests which were trigged by the mail.
+
+ $list = $status->get_names_of_subtests_hit ()
+ After a mail message has been checked, this method can be called. It
+ will return a comma-separated string, listing all the symbolic test
+ names of the meta-rule sub-tests which were trigged by the mail.
+ Sub-tests are the normally-hidden rules, which score 0 and have
+ names beginning with two underscores, used in meta rules.
+
+ $num = $status->get_score ()
+ After a mail message has been checked, this method can be called. It
+ will return the message's score.
+
+ $num = $status->get_required_score ()
+ After a mail message has been checked, this method can be called. It
+ will return the score required for a mail to be considered spam.
+
+ $num = $status->get_autolearn_status ()
+ After a mail message has been checked, this method can be called. It
+ will return one of the following strings depending on whether the
+ mail was auto-learned or not: "ham", "no", "spam", "disabled",
+ "failed", "unavailable".
+
+ $report = $status->get_report ()
+ Deliver a "spam report" on the checked mail message. This contains
+ details of how many spam detection rules it triggered.
+
+ The report is returned as a multi-line string, with the lines
+ separated by "\n" characters.
+
+ $preview = $status->get_content_preview ()
+ Give a "preview" of the content.
+
+ This is returned as a multi-line string, with the lines separated by
+ "\n" characters, containing a fully-decoded, safe, plain-text sample
+ of the first few lines of the message body.
+
+ $msg = $status->get_message()
+ Return the object representing the message being scanned.
+
+ $status->rewrite_mail ()
+ Rewrite the mail message. This will at minimum add headers, and at
+ maximum MIME-encapsulate the message text, to reflect its spam or
+ not-spam status. The function will return a scalar of the rewritten
+ message.
+
+ The actual modifications depend on the configuration (see
+ "Mail::SpamAssassin::Conf" for more information).
+
+ The possible modifications are as follows:
+
+ To:, From: and Subject: modification on spam mails
+ Depending on the configuration, the To: and From: lines can have
+ a user-defined RFC 2822 comment appended for spam mail. The
+ subject line may have a user-defined string prepended to it for
+ spam mail.
+
+ X-Spam-* headers for all mails
+ Depending on the configuration, zero or more headers with names
+ beginning with "X-Spam-" will be added to mail depending on
+ whether it is spam or ham.
+
+ spam message with report_safe
+ If report_safe is set to true (1), then spam messages are
+ encapsulated into their own message/rfc822 MIME attachment
+ without any modifications being made.
+
+ If report_safe is set to false (0), then the message will only
+ have the above headers added/modified.
+
+ $status->set_tag($tagname, $value)
+ Set a template tag, as used in "add_header", report templates, etc.
+ This API is intended for use by plugins. Tag names will be converted
+ to an all-uppercase representation internally.
+
+ $value can be a subroutine reference, which will be evaluated each
+ time the template is expanded. Note that perl supports closures,
+ which means that variables set in the caller's scope can be accessed
+ inside this "sub". For example:
+
+ my $text = "hello world!";
+ $status->set_tag("FOO", sub {
+ return $text;
+ });
+
+ See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" section for more
+ details on how template tags are used.
+
+ $string = $status->get_tag($tagname)
+ Get the current value of a template tag, as used in "add_header",
+ report templates, etc. This API is intended for use by plugins. Tag
+ names will be converted to an all-uppercase representation
+ internally. See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" section
+ for more details on tags.
+
+ "undef" will be returned if a tag by that name has not been defined.
+
+ $status->finish ()
+ Indicate that this $status object is finished with, and can be
+ destroyed.
+
+ If you are using SpamAssassin in a persistent environment, or
+ checking many mail messages from one "Mail::SpamAssassin" factory,
+ this method should be called to ensure Perl's garbage collection
+ will clean up old status objects.
+
+ $name = $status->get_current_eval_rule_name()
+ Return the name of the currently-running eval rule. "undef" is
+ returned if no eval rule is currently being run. Useful for plugins
+ to determine the current rule name while inside an eval test
+ function call.
+
+ $status->get (header_name [, default_value])
+ Returns a message header, pseudo-header, real name or address.
+ "header_name" is the name of a mail header, such as 'Subject', 'To',
+ etc. If "default_value" is given, it will be used if the requested
+ "header_name" does not exist.
+
+ Appending ":raw" to the header name will inhibit decoding of
+ quoted-printable or base-64 encoded strings.
+
+ Appending ":addr" to the header name will cause everything except
+ the first email address to be removed from the header. For example,
+ all of the following will result in "example@foo":
+
+ example@foo
+ example@foo (Foo Blah)
+ example@foo, example@bar
+ display: example@foo (Foo Blah), example@bar ;
+ Foo Blah <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@foo>
+
+ Appending ":name" to the header name will cause everything except
+ the first real name to be removed from the header. For example, all
+ of the following will result in "Foo Blah"
+
+ example@foo (Foo Blah)
+ example@foo (Foo Blah), example@bar
+ display: example@foo (Foo Blah), example@bar ;
+ Foo Blah <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@foo>
+
+ There are several special pseudo-headers that can be specified:
+
+ "ALL" can be used to mean the text of all the message's headers.
+ "ToCc" can be used to mean the contents of both the 'To' and 'Cc'
+ headers.
+ "EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the
+ SMTP transaction that delivered this message, if this data has been
+ made available by the SMTP server.
+ "MESSAGEID" is a symbol meaning all Message-Id's found in the
+ message; some mailing list software moves the real 'Message-Id' to
+ 'Resent-Message-Id' or 'X-Message-Id', then uses its own one in the
+ 'Message-Id' header. The value returned for this symbol is the text
+ from all 3 headers, separated by newlines.
+ "X-Spam-Relays-Untrusted" is the generated metadata of untrusted
+ relays the message has passed through
+ "X-Spam-Relays-Trusted" is the generated metadata of trusted relays
+ the message has passed through
+
+ $status->get_uri_list ()
+ Returns an array of all unique URIs found in the message. It takes a
+ combination of the URIs found in the rendered (decoded and HTML
+ stripped) body and the URIs found when parsing the HTML in the
+ message. Will also set $status->{uri_list} (the array as returned by
+ this function).
+
+ The returned array will include the "raw" URI as well as "slightly
+ cooked" versions. For example, the single URI
+ 'http://%77w%77.example.com/' will get turned into: (
+ 'http://%77w%77.example.com/', 'http://www.example.com/' )
+
+ $status->get_uri_detail_list ()
+ Returns a hash reference of all unique URIs found in the message and
+ various data about where the URIs were found in the message. It
+ takes a combination of the URIs found in the rendered (decoded and
+ HTML stripped) body and the URIs found when parsing the HTML in the
+ message. Will also set $status->{uri_detail_list} (the hash
+ reference as returned by this function). This function will also set
+ $status->{uri_domain_count} (count of unique domains).
+
+ The hash format looks something like this:
+
+ raw_uri => {
+ types => { a => 1, img => 1, parsed => 1 },
+ cleaned => [ canonified_uri ],
+ anchor_text => [ "click here", "no click here" ],
+ domains => { domain1 => 1, domain2 => 1 },
+ }
+
+ "raw_uri" is whatever the URI was in the message itself
+ (http://spamassassin.apache%2Eorg/).
+
+ "types" is a hash of the HTML tags (lowercase) which referenced the
+ raw_uri. *parsed* is a faked type which specifies that the raw_uri
+ was seen in the rendered text.
+
+ "cleaned" is an array of the raw and canonified version of the
+ raw_uri (http://spamassassin.apache%2Eorg/,
+ http://spamassassin.apache.org/).
+
+ "anchor_text" is an array of the anchor text (text between <a> and
+ </a>), if any, which linked to the URI.
+
+ "domains" is a hash of the domains found in the canonified URIs.
+
+ $status->clear_test_state()
+ Clear test state, including test log messages from
+ "$status->test_log()".
+
+ $status->create_fulltext_tmpfile (fulltext_ref)
+ This function creates a temporary file containing the passed scalar
+ reference data (typically the full/pristine text of the message).
+ This is typically used by external programs like pyzor and dccproc,
+ to avoid hangs due to buffering issues. Methods that need this,
+ should call $self->create_fulltext_tmpfile($fulltext) to retrieve
+ the temporary filename; it will be created if it has not already
+ been.
+
+ Note: This can only be called once until
+ $status->delete_fulltext_tmpfile() is called.
+
+ $status->delete_fulltext_tmpfile ()
+ Will cleanup after a $status->create_fulltext_tmpfile() call.
+ Deletes the temporary file and uncaches the filename.
+
+SEE ALSO
+ "Mail::SpamAssassin" "spamassassin"
+
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.html?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.html (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.html Mon Oct 16 08:57:50 2006
@@ -0,0 +1,112 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...</pre>
+<p>SpamAssassin will call:</p>
+<pre>
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>All persistent address list implementations, used by the auto-whitelist
+code to track known-good email addresses, use this as a base class.</p>
+<p>See <code>Mail::SpamAssassin::DBBasedAddrList</code> for an example.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_new">$factory = PersistentAddrListSubclass->new();</a></strong><br />
+</dt>
+<dd>
+This creates a factory object, which SpamAssassin will call to create
+a new checker object for the persistent address list.
+</dd>
+<p></p>
+<dt><strong><a name="item_new_checker">my $addrlist = $factory->new_checker();</a></strong><br />
+</dt>
+<dd>
+Create a new address-list checker object from the factory. Called by the
+SpamAssassin classes.
+</dd>
+<p></p>
+<dt><strong><a name="item_get_addr_entry">$entry = $addrlist->get_addr_entry ($addr);</a></strong><br />
+</dt>
+<dd>
+Given an email address <code>$addr</code>, return an entry object with the details of
+that address.
+</dd>
+<dd>
+<p>The entry object is a reference to a hash, which must contain at least
+two keys: <code>count</code>, which is the count of times that address has been
+encountered before; and <code>totscore</code>, which is the total of all scores for
+messages associated with that address. From these two fields, an average
+score will be calculated, and the score for the current message will be
+regressed towards that mean message score.</p>
+</dd>
+<dd>
+<p>The hash can contain whatever other data your back-end needs to store,
+under other keys.</p>
+</dd>
+<dd>
+<p>The method should never return <code>undef</code>, or a hash that does not contain
+a <code>count</code> key and a <code>totscore</code> key.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_score">$entry = $addrlist->add_score($entry, $score);</a></strong><br />
+</dt>
+<dd>
+This method should add the given score to the whitelist database for the
+given entry, and then return the new entry.
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_entry">$entry = $addrlist->remove_entry ($entry);</a></strong><br />
+</dt>
+<dd>
+This method should remove the given entry from the whitelist database.
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$entry = $addrlist->finish ();</a></strong><br />
+</dt>
+<dd>
+Clean up, if necessary. Called by SpamAssassin when it has finished
+checking, or adding to, the auto-whitelist database.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.txt?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.txt (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PersistentAddrList.txt Mon Oct 16 08:57:50 2006
@@ -0,0 +1,59 @@
+NAME
+ Mail::SpamAssassin::PersistentAddrList - persistent address list base
+ class
+
+SYNOPSIS
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...
+
+ SpamAssassin will call:
+
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...
+
+DESCRIPTION
+ All persistent address list implementations, used by the auto-whitelist
+ code to track known-good email addresses, use this as a base class.
+
+ See "Mail::SpamAssassin::DBBasedAddrList" for an example.
+
+METHODS
+ $factory = PersistentAddrListSubclass->new();
+ This creates a factory object, which SpamAssassin will call to
+ create a new checker object for the persistent address list.
+
+ my $addrlist = $factory->new_checker();
+ Create a new address-list checker object from the factory. Called by
+ the SpamAssassin classes.
+
+ $entry = $addrlist->get_addr_entry ($addr);
+ Given an email address $addr, return an entry object with the
+ details of that address.
+
+ The entry object is a reference to a hash, which must contain at
+ least two keys: "count", which is the count of times that address
+ has been encountered before; and "totscore", which is the total of
+ all scores for messages associated with that address. From these two
+ fields, an average score will be calculated, and the score for the
+ current message will be regressed towards that mean message score.
+
+ The hash can contain whatever other data your back-end needs to
+ store, under other keys.
+
+ The method should never return "undef", or a hash that does not
+ contain a "count" key and a "totscore" key.
+
+ $entry = $addrlist->add_score($entry, $score);
+ This method should add the given score to the whitelist database for
+ the given entry, and then return the new entry.
+
+ $entry = $addrlist->remove_entry ($entry);
+ This method should remove the given entry from the whitelist
+ database.
+
+ $entry = $addrlist->finish ();
+ Clean up, if necessary. Called by SpamAssassin when it has finished
+ checking, or adding to, the auto-whitelist database.
+
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.html?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.html (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.html Mon Oct 16 08:57:50 2006
@@ -0,0 +1,828 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Plugin - SpamAssassin plugin base class</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <ul>
+
+ <li><a href="#spamassassin_configuration_">SpamAssassin configuration:</a></li>
+ <li><a href="#perl_code_">Perl code:</a></li>
+ </ul>
+
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#interface">INTERFACE</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#helper_apis">HELPER APIS</a></li>
+ <li><a href="#registering_eval_rules">REGISTERING EVAL RULES</a></li>
+ <li><a href="#standard_arguments_for_rule_types">STANDARD ARGUMENTS FOR RULE TYPES</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin - SpamAssassin plugin base class</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<h2><a name="spamassassin_configuration_">SpamAssassin configuration:</a></h2>
+<pre>
+ loadplugin MyPlugin /path/to/myplugin.pm</pre>
+<p>
+</p>
+<h2><a name="perl_code_">Perl code:</a></h2>
+<pre>
+ package MyPlugin;</pre>
+<pre>
+ use Mail::SpamAssassin::Plugin;
+ our @ISA = qw(Mail::SpamAssassin::Plugin);</pre>
+<pre>
+ sub new {
+ my ($class, $mailsa) = @_;
+
+ # the usual perlobj boilerplate to create a subclass object
+ $class = ref($class) || $class;
+ my $self = $class->SUPER::new($mailsa);
+ bless ($self, $class);
+
+ # then register an eval rule, if desired...
+ $self->register_eval_rule ("check_for_foo");</pre>
+<pre>
+ # and return the new plugin object
+ return $self;
+ }</pre>
+<pre>
+ ...methods...</pre>
+<pre>
+ 1;</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This is the base class for SpamAssassin plugins; all plugins must be objects
+that implement this class.</p>
+<p>This class provides no-op stub methods for all the callbacks that a plugin
+can receive. It is expected that your plugin will override one or more
+of these stubs to perform its actions.</p>
+<p>SpamAssassin implements a plugin chain; each callback event is passed to each
+of the registered plugin objects in turn. Any plugin can call
+<a href="#item_inhibit_further_callbacks"><code>$self->inhibit_further_callbacks()</code></a> to block delivery of that event to
+later plugins in the chain. This is useful if the plugin has handled the
+event, and there will be no need for later plugins to handle it as well.</p>
+<p>If you're looking to write a simple eval rule, skip straight to
+<a href="#item_register_eval_rule"><code>register_eval_rule()</code></a>, below.</p>
+<p>
+</p>
+<hr />
+<h1><a name="interface">INTERFACE</a></h1>
+<p>In all the plugin APIs below, <code>options</code> refers to a reference to a hash
+containing name-value pairs. This is used to ensure future-compatibility, in
+that we can add new options in future without affecting objects built to an
+earlier version of the API.</p>
+<p>For example, here would be how to print out the <a href="#item_line"><code>line</code></a> item in a
+<a href="#item_parse_config"><code>parse_config()</code></a> method:</p>
+<pre>
+ sub parse_config {
+ my ($self, $opts) = @_;
+ print "MyPlugin: parse_config got ".$opts->{line}."\n";
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<p>The following methods can be overridden by subclasses to handle events
+that SpamAssassin will call back to:</p>
+<dl>
+<dt><strong><a name="item_new">$plugin = MyPluginClass->new ($mailsaobject)</a></strong><br />
+</dt>
+<dd>
+Constructor. Plugins that need to register themselves will need to
+define their own; the default super-class constructor will work fine
+for plugins that just override a method.
+</dd>
+<dd>
+<p>Note that subclasses must provide the <code>$mailsaobject</code> to the
+superclass constructor, like so:</p>
+</dd>
+<dd>
+<pre>
+ my $self = $class->SUPER::new($mailsaobject);</pre>
+</dd>
+<dd>
+<p>Lifecycle note: plugins that will need to store per-scan state should not store
+that on the Plugin object; see <a href="#item_check_start"><code>check_start()</code></a> below. It is also likewise
+recommended that configuration settings be stored on the Conf object; see
+<a href="#item_parse_config"><code>parse_config()</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_parse_config">$plugin->parse_config ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Parse a configuration line that hasn't already been handled. <code>options</code>
+is a reference to a hash containing these options:
+</dd>
+<dl>
+<dt><strong><a name="item_line">line</a></strong><br />
+</dt>
+<dd>
+The line of configuration text to parse. This has leading and trailing
+whitespace, and comments, removed.
+</dd>
+<p></p>
+<dt><strong><a name="item_key">key</a></strong><br />
+</dt>
+<dd>
+The configuration key; ie. the first ``word'' on the line.
+</dd>
+<p></p>
+<dt><strong><a name="item_value">value</a></strong><br />
+</dt>
+<dd>
+The configuration value; everything after the first ``word'' and
+any whitespace after that.
+</dd>
+<p></p>
+<dt><strong><a name="item_conf">conf</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p>
+<dt><strong><a name="item_user_config">user_config</a></strong><br />
+</dt>
+<dd>
+A boolean: <code>1</code> if reading a user's configuration, <code>0</code> if reading the
+system-wide configuration files.
+</dd>
+<p></p></dl>
+<p>If the configuration line was a setting that is handled by this plugin, the
+method implementation should call <a href="#item_inhibit_further_callbacks"><code>$self->inhibit_further_callbacks()</code></a>.</p>
+<p>If the setting is not handled by this plugin, the method should return <code>0</code> so
+that a later plugin may handle it, or so that SpamAssassin can output a warning
+message to the user if no plugin understands it.</p>
+<p>Lifecycle note: it is suggested that configuration be stored on the
+<code>Mail::SpamAssassin::Conf</code> object in use, instead of the plugin object itself.
+That can be found as <code>$plugin->{main}->{conf}</code>. This allows per-user and
+system-wide configuration to be dealt with correctly, with per-user overriding
+system-wide.</p>
+<dt><strong><a name="item_finish_parsing_end">$plugin->finish_parsing_end ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that the configuration parsing has just finished, and SpamAssassin
+is nearly ready to check messages.
+</dd>
+<dd>
+<p><code>options</code> is a reference to a hash containing these options:</p>
+</dd>
+<dl>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p></dl>
+<p>Note: there are no guarantees that the internal data structures of
+SpamAssassin will not change from release to release. In particular to
+this plugin hook, if you modify the rules data structures in a
+third-party plugin, all bets are off until such time that an API is
+present for modifying that configuration data.</p>
+<dt><strong><a name="item_signal_user_changed">$plugin->signal_user_changed ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that the current user has changed for a new one.
+</dd>
+<dl>
+<dt><strong><a name="item_username">username</a></strong><br />
+</dt>
+<dd>
+The new user's username.
+</dd>
+<p></p>
+<dt><strong><a name="item_user_dir">user_dir</a></strong><br />
+</dt>
+<dd>
+The new user's home directory. (equivalent to <code>~</code>.)
+</dd>
+<p></p>
+<dt><strong><a name="item_userstate_dir">userstate_dir</a></strong><br />
+</dt>
+<dd>
+The new user's storage directory. (equivalent to <code>~/.spamassassin</code>.)
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_services_authorized_for_username">$plugin->services_authorized_for_username ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Validates that a given username is authorized to use certain services.
+</dd>
+<dd>
+<p>In order to authorize a user, the plugin should first check that it can
+handle any of the services passed into the method and then set the value
+for each allowed service to true (or any non-negative value).</p>
+</dd>
+<dd>
+<p>The current supported services are: bayessql</p>
+</dd>
+<dl>
+<dt><strong>username</strong><br />
+</dt>
+<dd>
+A username
+</dd>
+<p></p>
+<dt><strong><a name="item_services">services</a></strong><br />
+</dt>
+<dd>
+Reference to a hash containing the services you want to check.
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'bayessql' => 0</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<p></p>
+<dt><strong>conf</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Conf</code> object on which the configuration
+data should be stored.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_start">$plugin->check_start ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message check operation is starting.
+</dd>
+<dl>
+<dt><strong><a name="item_permsgstatus">permsgstatus</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<dd>
+<p>Lifecycle note: it is recommended that rules that need to track test state on a
+per-scan basis should store that state on this object, not on the plugin object
+itself, since the plugin object will be shared between all active scanners.</p>
+</dd>
+<dd>
+<p>The message being scanned is accessible through the
+<code>$permsgstatus->get_message()</code> API; there are a number of other public
+APIs on that object, too. See <code>Mail::SpamAssassin::PerMsgStatus</code> perldoc.</p>
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_extract_metadata">$plugin->extract_metadata ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message is being mined for metadata. Some plugins may wish
+to add their own metadata as well.
+</dd>
+<dl>
+<dt><strong><a name="item_msg">msg</a></strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::Message</code> object for this message.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_parsed_metadata">$plugin->parsed_metadata ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message's metadata has been parsed, and can now be
+accessed by the plugin.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_tick">$plugin->check_tick ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called periodically during a message check operation. A callback set for
+this method is a good place to run through an event loop dealing with
+network events triggered in a <code>parse_metadata</code> method, for example.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_post_dnsbl">$plugin->check_post_dnsbl ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called after the DNSBL results have been harvested. This is a good
+place to harvest your own asynchronously-started network lookups.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_post_learn">$plugin->check_post_learn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called after auto-learning may (or may not) have taken place. If you
+wish to perform additional learning, whether or not auto-learning
+happens, this is the place to do it.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_check_end">$plugin->check_end ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message check operation has just finished, and the
+results are about to be returned to the caller.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+The current score, names of rules that hit, etc. can be retrieved
+using the public APIs on this object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_autolearn_discriminator">$plugin->autolearn_discriminator ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Control whether a just-scanned message should be learned as either
+spam or ham. This method should return one of <code>1</code> to learn
+the message as spam, <code>0</code> to learn as ham, or <code>undef</code> to not
+learn from the message at all.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_autolearn">$plugin->autolearn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a message is about to be auto-learned as either ham or spam.
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p>
+<dt><strong><a name="item_isspam">isspam</a></strong><br />
+</dt>
+<dd>
+<code>1</code> if the message is spam, <code>0</code> if ham.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_per_msg_finish">$plugin->per_msg_finish ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Signals that a <code>Mail::SpamAssassin::PerMsgStatus</code> object is being
+destroyed, and any per-scan context held on that object by this
+plugin should be destroyed as well.
+</dd>
+<dd>
+<p>Normally, any member variables on the <code>PerMsgStatus</code> object will be cleaned up
+automatically -- but if your plugin has made a circular reference on that
+object, this is the place to break them so that garbage collection can operate
+correctly.</p>
+</dd>
+<dl>
+<dt><strong>permsgstatus</strong><br />
+</dt>
+<dd>
+The <code>Mail::SpamAssassin::PerMsgStatus</code> context object for this scan.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_learn">$plugin->bayes_learn ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes learn operation.
+</dd>
+<dd>
+<p>This phase is the best place to map the raw (original) token value
+to the SHA1 hashed value.</p>
+</dd>
+<dl>
+<dt><strong><a name="item_toksref">toksref</a></strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. The hash takes the
+format of:
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'SHA1 Hash Value' => 'raw (original) value'</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<dd>
+<p>NOTE: This data structure has changed since it was originally introduced
+in version 3.0.0. The values are no longer perl anonymous hashes, they
+are a single string containing the raw token value. You can test for
+backwards compatability by checking to see if the value for a key is a
+reference to a perl HASH, for instance:</p>
+</dd>
+<dd>
+<p>if (ref($toksref->{$sometokenkey}) eq 'HASH') {...</p>
+</dd>
+<dd>
+<p>If it is, then you are using the old interface, otherwise you are using
+the current interface.</p>
+</dd>
+<p></p>
+<dt><strong>isspam</strong><br />
+</dt>
+<dd>
+Boolean value stating what flavor of message the tokens represent, if
+true then message was specified as spam, false is nonspam. Note, when
+function is scan then isspam value is not valid.
+</dd>
+<p></p>
+<dt><strong><a name="item_msgid">msgid</a></strong><br />
+</dt>
+<dd>
+Generated message id of the message just learned.
+</dd>
+<p></p>
+<dt><strong><a name="item_msgatime">msgatime</a></strong><br />
+</dt>
+<dd>
+Received date of the current message or current time if received date
+could not be determined. In addition, if the receive date is more than
+24 hrs into the future it will be reset to current datetime.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_forget">$plugin->bayes_forget ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes forget operation.
+</dd>
+<dl>
+<dt><strong>toksref</strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. See bayes_learn
+documentation for additional information on the format.
+</dd>
+<p></p>
+<dt><strong>isspam</strong><br />
+</dt>
+<dd>
+Boolean value stating what flavor of message the tokens represent, if
+true then message was specified as spam, false is nonspam. Note, when
+function is scan then isspam value is not valid.
+</dd>
+<p></p>
+<dt><strong>msgid</strong><br />
+</dt>
+<dd>
+Generated message id of the message just forgotten.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_bayes_scan">$plugin->bayes_scan ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called at the end of a bayes scan operation. NOTE: Will not be
+called in case of error or if the message is otherwise skipped.
+</dd>
+<dl>
+<dt><strong>toksref</strong><br />
+</dt>
+<dd>
+Reference to hash returned by call to tokenize. See bayes_learn
+documentation for additional information on the format.
+</dd>
+<p></p>
+<dt><strong><a name="item_probsref">probsref</a></strong><br />
+</dt>
+<dd>
+Reference to hash of calculated probabilities for tokens found in
+the database.
+</dd>
+<dd>
+<p>{</p>
+</dd>
+<dd>
+<pre>
+ 'SHA1 Hash Value' => {</pre>
+</dd>
+<dd>
+<pre>
+ 'prob' => 'calculated probability',</pre>
+</dd>
+<dd>
+<pre>
+ 'spam_count' => 'Total number of spam msgs w/ token',</pre>
+</dd>
+<dd>
+<pre>
+ 'ham_count' => 'Total number of ham msgs w/ token',</pre>
+</dd>
+<dd>
+<pre>
+ 'atime' => 'Atime value for token in database'</pre>
+</dd>
+<dd>
+<pre>
+ }</pre>
+</dd>
+<dd>
+<p>}</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_score">score</a></strong><br />
+</dt>
+<dd>
+Score calculated for this particular message.
+</dd>
+<p></p>
+<dt><strong>msgatime</strong><br />
+</dt>
+<dd>
+Calculated atime of the message just learned, note it may have been adjusted
+if it was determined to be too far into the future.
+</dd>
+<p></p>
+<dt><strong><a name="item_significant_tokens">significant_tokens</a></strong><br />
+</dt>
+<dd>
+Array ref of the tokens found to be significant in determining the score for
+this message.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_plugin_report">$plugin->plugin_report ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called if the message is to be reported as spam. If the reporting system is
+available, the variable <code>$options-<gt</code>{report}-><gt>report_available}> should
+be set to <code>1</code>; if the reporting system successfully reported the message, the
+variable <code>$options-<gt</code>{report}-><gt>report_return}> should be set to <code>1</code>.
+</dd>
+<dl>
+<dt><strong><a name="item_report">report</a></strong><br />
+</dt>
+<dd>
+Reference to the Reporter object (<code>$options-<gt</code>{report}> in the
+paragraph above.)
+</dd>
+<p></p>
+<dt><strong><a name="item_text">text</a></strong><br />
+</dt>
+<dd>
+Reference to a markup removed copy of the message in scalar string format.
+</dd>
+<p></p>
+<dt><strong>msg</strong><br />
+</dt>
+<dd>
+Reference to the original message object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_plugin_revoke">$plugin->plugin_revoke ( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called if the message is to be reported as ham (revokes a spam report). If the
+reporting system is available, the variable
+<code>$options-<gt</code>{revoke}-><gt>revoke_available}> should be set to <code>1</code>; if the
+reporting system successfully revoked the message, the variable
+<code>$options-<gt</code>{revoke}-><gt>revoke_return}> should be set to <code>1</code>.
+</dd>
+<dl>
+<dt><strong><a name="item_revoke">revoke</a></strong><br />
+</dt>
+<dd>
+Reference to the Reporter object (<code>$options-<gt</code>{revoke}> in the
+paragraph above.)
+</dd>
+<p></p>
+<dt><strong>text</strong><br />
+</dt>
+<dd>
+Reference to a markup removed copy of the message in scalar string format.
+</dd>
+<p></p>
+<dt><strong>msg</strong><br />
+</dt>
+<dd>
+Reference to the original message object.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_whitelist_address">$plugin->whitelist_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to add an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong><a name="item_address">address</a></strong><br />
+</dt>
+<dd>
+Address you wish to add.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_blacklist_address">$plugin->blacklist_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to add an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong>address</strong><br />
+</dt>
+<dd>
+Address you wish to add.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_remove_address">$plugin->remove_address( { options ... } )</a></strong><br />
+</dt>
+<dd>
+Called when a request is made to remove an address to a
+persistent address list.
+</dd>
+<dl>
+<dt><strong>address</strong><br />
+</dt>
+<dd>
+Address you wish to remove.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_spamd_child_init">$plugin->spamd_child_init ()</a></strong><br />
+</dt>
+<dd>
+Called when a new child starts up under spamd.
+</dd>
+<p></p>
+<dt><strong><a name="item_spamd_child_post_connection_close">$plugin->spamd_child_post_connection_close ()</a></strong><br />
+</dt>
+<dd>
+Called when child returns from handling a connection.
+</dd>
+<dd>
+<p>If there was an accept failure, the child will die and this code will
+not be called.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$plugin->finish ()</a></strong><br />
+</dt>
+<dd>
+Called when the <code>Mail::SpamAssassin</code> object is destroyed.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="helper_apis">HELPER APIS</a></h1>
+<p>These methods provide an API for plugins to register themselves
+to receive specific events, or control the callback chain behaviour.</p>
+<dl>
+<dt><strong><a name="item_register_eval_rule">$plugin->register_eval_rule ($nameofevalsub)</a></strong><br />
+</dt>
+<dd>
+Plugins that implement an eval test will need to call this, so that
+SpamAssassin calls into the object when that eval test is encountered.
+See the <strong>REGISTERING EVAL RULES</strong> section for full details.
+</dd>
+<p></p>
+<dt><strong><a name="item_inhibit_further_callbacks">$plugin-><code>inhibit_further_callbacks()</code></a></strong><br />
+</dt>
+<dd>
+Tells the plugin handler to inhibit calling into other plugins in the plugin
+chain for the current callback. Frequently used when parsing configuration
+settings using <a href="#item_parse_config"><code>parse_config()</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_dbg"><code>dbg($message)</code></a></strong><br />
+</dt>
+<dd>
+Output a debugging message <code>$message</code>, if the SpamAssassin object is running
+with debugging turned on.
+</dd>
+<dd>
+<p><em>NOTE:</em> This function is not available in the package namespace
+of general plugins and can't be called via $self->dbg(). If a
+plugin wishes to output debug information, it should call
+<a href="#item_dbg"><code>Mail::SpamAssassin::Plugin::dbg($msg)</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_info"><code>info($message)</code></a></strong><br />
+</dt>
+<dd>
+Output an informational message <code>$message</code>, if the SpamAssassin object
+is running with informational messages turned on.
+</dd>
+<dd>
+<p><em>NOTE:</em> This function is not available in the package namespace
+of general plugins and can't be called via $self->dbg(). If a
+plugin wishes to output debug information, it should call
+<a href="#item_dbg"><code>Mail::SpamAssassin::Plugin::dbg($msg)</code></a>.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="registering_eval_rules">REGISTERING EVAL RULES</a></h1>
+<p>Plugins that implement an eval test must register the methods that can be
+called from rules in the configuration files, in the plugin class' constructor.</p>
+<p>For example,</p>
+<pre>
+ $plugin->register_eval_rule ('check_for_foo')</pre>
+<p>will cause <code>$plugin->check_for_foo()</code> to be called for this
+SpamAssassin rule:</p>
+<pre>
+ header FOO_RULE eval:check_for_foo()</pre>
+<p>Note that eval rules are passed the following arguments:</p>
+<dl>
+<dt><strong><a name="item__2d_the_plugin_object_itself">- The plugin object itself</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_the_mail_3a_3aspamassassin_3a_3apermsgstatus_o">- The <code>Mail::SpamAssassin::PerMsgStatus</code> object calling the rule</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_standard_arguments_for_the_rule_type_in_use">- standard arguments for the rule type in use</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_any_and_all_arguments_as_specified_in_the_conf">- any and all arguments as specified in the configuration file</a></strong><br />
+</dt>
+</dl>
+<p>In other words, the eval test method should look something like this:</p>
+<pre>
+ sub check_for_foo {
+ my ($self, $permsgstatus, ...arguments...) = @_;
+ ...code returning 0 or 1
+ }</pre>
+<p>Note that the headers can be accessed using the <code>get()</code> method on the
+<code>Mail::SpamAssassin::PerMsgStatus</code> object, and the body by
+<code>get_decoded_stripped_body_text_array()</code> and other similar methods.
+Similarly, the <code>Mail::SpamAssassin::Conf</code> object holding the current
+configuration may be accessed through <code>$permsgstatus->{main}->{conf}</code>.</p>
+<p>The eval rule should return <code>1</code> for a hit, or <code>0</code> if the rule
+is not hit.</p>
+<p>State for a single message being scanned should be stored on the <code>$checker</code>
+object, not on the <code>$self</code> object, since <code>$self</code> persists between scan
+operations. See the 'lifecycle note' on the <a href="#item_check_start"><code>check_start()</code></a> method above.</p>
+<p>
+</p>
+<hr />
+<h1><a name="standard_arguments_for_rule_types">STANDARD ARGUMENTS FOR RULE TYPES</a></h1>
+<p>Plugins will be called with the same arguments as a standard EvalTest.
+Different rule types receive different information by default:</p>
+<dl>
+<dt><strong><a name="item__2d_header_tests_3a_no_extra_arguments">- header tests: no extra arguments</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_body_tests_3a_fully_rendered_message_as_array_">- body tests: fully rendered message as array reference</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_rawbody_tests_3a_fully_decoded_message_as_arra">- rawbody tests: fully decoded message as array reference</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_full_tests_3a_pristine_message_as_scalar_refer">- full tests: pristine message as scalar reference</a></strong><br />
+</dt>
+</dl>
+<p>The configuration file arguments will be passed in after the standard
+arguments.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::SpamAssassin</code></p>
+<p><code>Mail::SpamAssassin::PerMsgStatus</code></p>
+<p><a href="http://wiki.apache.org/spamassassin/PluginWritingTips">http://wiki.apache.org/spamassassin/PluginWritingTips</a></p>
+<p><a href="http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163">http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163</a></p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.txt?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.txt (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin.txt Mon Oct 16 08:57:50 2006
@@ -0,0 +1,540 @@
+NAME
+ Mail::SpamAssassin::Plugin - SpamAssassin plugin base class
+
+SYNOPSIS
+ SpamAssassin configuration:
+ loadplugin MyPlugin /path/to/myplugin.pm
+
+ Perl code:
+ package MyPlugin;
+
+ use Mail::SpamAssassin::Plugin;
+ our @ISA = qw(Mail::SpamAssassin::Plugin);
+
+ sub new {
+ my ($class, $mailsa) = @_;
+
+ # the usual perlobj boilerplate to create a subclass object
+ $class = ref($class) || $class;
+ my $self = $class->SUPER::new($mailsa);
+ bless ($self, $class);
+
+ # then register an eval rule, if desired...
+ $self->register_eval_rule ("check_for_foo");
+
+ # and return the new plugin object
+ return $self;
+ }
+
+ ...methods...
+
+ 1;
+
+DESCRIPTION
+ This is the base class for SpamAssassin plugins; all plugins must be
+ objects that implement this class.
+
+ This class provides no-op stub methods for all the callbacks that a
+ plugin can receive. It is expected that your plugin will override one or
+ more of these stubs to perform its actions.
+
+ SpamAssassin implements a plugin chain; each callback event is passed to
+ each of the registered plugin objects in turn. Any plugin can call
+ "$self->inhibit_further_callbacks()" to block delivery of that event to
+ later plugins in the chain. This is useful if the plugin has handled the
+ event, and there will be no need for later plugins to handle it as well.
+
+ If you're looking to write a simple eval rule, skip straight to
+ "register_eval_rule()", below.
+
+INTERFACE
+ In all the plugin APIs below, "options" refers to a reference to a hash
+ containing name-value pairs. This is used to ensure
+ future-compatibility, in that we can add new options in future without
+ affecting objects built to an earlier version of the API.
+
+ For example, here would be how to print out the "line" item in a
+ "parse_config()" method:
+
+ sub parse_config {
+ my ($self, $opts) = @_;
+ print "MyPlugin: parse_config got ".$opts->{line}."\n";
+ }
+
+METHODS
+ The following methods can be overridden by subclasses to handle events
+ that SpamAssassin will call back to:
+
+ $plugin = MyPluginClass->new ($mailsaobject)
+ Constructor. Plugins that need to register themselves will need to
+ define their own; the default super-class constructor will work fine
+ for plugins that just override a method.
+
+ Note that subclasses must provide the $mailsaobject to the
+ superclass constructor, like so:
+
+ my $self = $class->SUPER::new($mailsaobject);
+
+ Lifecycle note: plugins that will need to store per-scan state
+ should not store that on the Plugin object; see "check_start()"
+ below. It is also likewise recommended that configuration settings
+ be stored on the Conf object; see "parse_config()".
+
+ $plugin->parse_config ( { options ... } )
+ Parse a configuration line that hasn't already been handled.
+ "options" is a reference to a hash containing these options:
+
+ line
+ The line of configuration text to parse. This has leading and
+ trailing whitespace, and comments, removed.
+
+ key The configuration key; ie. the first "word" on the line.
+
+ value
+ The configuration value; everything after the first "word" and
+ any whitespace after that.
+
+ conf
+ The "Mail::SpamAssassin::Conf" object on which the configuration
+ data should be stored.
+
+ user_config
+ A boolean: 1 if reading a user's configuration, 0 if reading the
+ system-wide configuration files.
+
+ If the configuration line was a setting that is handled by this
+ plugin, the method implementation should call
+ "$self->inhibit_further_callbacks()".
+
+ If the setting is not handled by this plugin, the method should
+ return 0 so that a later plugin may handle it, or so that
+ SpamAssassin can output a warning message to the user if no plugin
+ understands it.
+
+ Lifecycle note: it is suggested that configuration be stored on the
+ "Mail::SpamAssassin::Conf" object in use, instead of the plugin
+ object itself. That can be found as "$plugin->{main}->{conf}". This
+ allows per-user and system-wide configuration to be dealt with
+ correctly, with per-user overriding system-wide.
+
+ $plugin->finish_parsing_end ( { options ... } )
+ Signals that the configuration parsing has just finished, and
+ SpamAssassin is nearly ready to check messages.
+
+ "options" is a reference to a hash containing these options:
+
+ conf
+ The "Mail::SpamAssassin::Conf" object on which the configuration
+ data should be stored.
+
+ Note: there are no guarantees that the internal data structures of
+ SpamAssassin will not change from release to release. In particular
+ to this plugin hook, if you modify the rules data structures in a
+ third-party plugin, all bets are off until such time that an API is
+ present for modifying that configuration data.
+
+ $plugin->signal_user_changed ( { options ... } )
+ Signals that the current user has changed for a new one.
+
+ username
+ The new user's username.
+
+ user_dir
+ The new user's home directory. (equivalent to "~".)
+
+ userstate_dir
+ The new user's storage directory. (equivalent to
+ "~/.spamassassin".)
+
+ $plugin->services_authorized_for_username ( { options ... } )
+ Validates that a given username is authorized to use certain
+ services.
+
+ In order to authorize a user, the plugin should first check that it
+ can handle any of the services passed into the method and then set
+ the value for each allowed service to true (or any non-negative
+ value).
+
+ The current supported services are: bayessql
+
+ username
+ A username
+
+ services
+ Reference to a hash containing the services you want to check.
+
+ {
+
+ 'bayessql' => 0
+
+ }
+
+ conf
+ The "Mail::SpamAssassin::Conf" object on which the configuration
+ data should be stored.
+
+ $plugin->check_start ( { options ... } )
+ Signals that a message check operation is starting.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ Lifecycle note: it is recommended that rules that need to track
+ test state on a per-scan basis should store that state on this
+ object, not on the plugin object itself, since the plugin object
+ will be shared between all active scanners.
+
+ The message being scanned is accessible through the
+ "$permsgstatus->get_message()" API; there are a number of other
+ public APIs on that object, too. See
+ "Mail::SpamAssassin::PerMsgStatus" perldoc.
+
+ $plugin->extract_metadata ( { options ... } )
+ Signals that a message is being mined for metadata. Some plugins may
+ wish to add their own metadata as well.
+
+ msg The "Mail::SpamAssassin::Message" object for this message.
+
+ $plugin->parsed_metadata ( { options ... } )
+ Signals that a message's metadata has been parsed, and can now be
+ accessed by the plugin.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->check_tick ( { options ... } )
+ Called periodically during a message check operation. A callback set
+ for this method is a good place to run through an event loop dealing
+ with network events triggered in a "parse_metadata" method, for
+ example.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->check_post_dnsbl ( { options ... } )
+ Called after the DNSBL results have been harvested. This is a good
+ place to harvest your own asynchronously-started network lookups.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->check_post_learn ( { options ... } )
+ Called after auto-learning may (or may not) have taken place. If you
+ wish to perform additional learning, whether or not auto-learning
+ happens, this is the place to do it.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->check_end ( { options ... } )
+ Signals that a message check operation has just finished, and the
+ results are about to be returned to the caller.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan. The current score, names of rules that hit, etc. can be
+ retrieved using the public APIs on this object.
+
+ $plugin->autolearn_discriminator ( { options ... } )
+ Control whether a just-scanned message should be learned as either
+ spam or ham. This method should return one of 1 to learn the message
+ as spam, 0 to learn as ham, or "undef" to not learn from the message
+ at all.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->autolearn ( { options ... } )
+ Signals that a message is about to be auto-learned as either ham or
+ spam.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ isspam
+ 1 if the message is spam, 0 if ham.
+
+ $plugin->per_msg_finish ( { options ... } )
+ Signals that a "Mail::SpamAssassin::PerMsgStatus" object is being
+ destroyed, and any per-scan context held on that object by this
+ plugin should be destroyed as well.
+
+ Normally, any member variables on the "PerMsgStatus" object will be
+ cleaned up automatically -- but if your plugin has made a circular
+ reference on that object, this is the place to break them so that
+ garbage collection can operate correctly.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for this
+ scan.
+
+ $plugin->bayes_learn ( { options ... } )
+ Called at the end of a bayes learn operation.
+
+ This phase is the best place to map the raw (original) token value
+ to the SHA1 hashed value.
+
+ toksref
+ Reference to hash returned by call to tokenize. The hash takes
+ the format of:
+
+ {
+
+ 'SHA1 Hash Value' => 'raw (original) value'
+
+ }
+
+ NOTE: This data structure has changed since it was originally
+ introduced in version 3.0.0. The values are no longer perl
+ anonymous hashes, they are a single string containing the raw
+ token value. You can test for backwards compatability by
+ checking to see if the value for a key is a reference to a perl
+ HASH, for instance:
+
+ if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
+
+ If it is, then you are using the old interface, otherwise you
+ are using the current interface.
+
+ isspam
+ Boolean value stating what flavor of message the tokens
+ represent, if true then message was specified as spam, false is
+ nonspam. Note, when function is scan then isspam value is not
+ valid.
+
+ msgid
+ Generated message id of the message just learned.
+
+ msgatime
+ Received date of the current message or current time if received
+ date could not be determined. In addition, if the receive date
+ is more than 24 hrs into the future it will be reset to current
+ datetime.
+
+ $plugin->bayes_forget ( { options ... } )
+ Called at the end of a bayes forget operation.
+
+ toksref
+ Reference to hash returned by call to tokenize. See bayes_learn
+ documentation for additional information on the format.
+
+ isspam
+ Boolean value stating what flavor of message the tokens
+ represent, if true then message was specified as spam, false is
+ nonspam. Note, when function is scan then isspam value is not
+ valid.
+
+ msgid
+ Generated message id of the message just forgotten.
+
+ $plugin->bayes_scan ( { options ... } )
+ Called at the end of a bayes scan operation. NOTE: Will not be
+ called in case of error or if the message is otherwise skipped.
+
+ toksref
+ Reference to hash returned by call to tokenize. See bayes_learn
+ documentation for additional information on the format.
+
+ probsref
+ Reference to hash of calculated probabilities for tokens found
+ in the database.
+
+ {
+
+ 'SHA1 Hash Value' => {
+
+ 'prob' => 'calculated probability',
+
+ 'spam_count' => 'Total number of spam msgs w/ token',
+
+ 'ham_count' => 'Total number of ham msgs w/ token',
+
+ 'atime' => 'Atime value for token in database'
+
+ }
+
+ }
+
+ score
+ Score calculated for this particular message.
+
+ msgatime
+ Calculated atime of the message just learned, note it may have
+ been adjusted if it was determined to be too far into the
+ future.
+
+ significant_tokens
+ Array ref of the tokens found to be significant in determining
+ the score for this message.
+
+ $plugin->plugin_report ( { options ... } )
+ Called if the message is to be reported as spam. If the reporting
+ system is available, the variable
+ "$options-<gt"{report}-><gt>report_available}> should be set to 1;
+ if the reporting system successfully reported the message, the
+ variable "$options-<gt"{report}-><gt>report_return}> should be set
+ to 1.
+
+ report
+ Reference to the Reporter object ("$options-<gt"{report}> in the
+ paragraph above.)
+
+ text
+ Reference to a markup removed copy of the message in scalar
+ string format.
+
+ msg Reference to the original message object.
+
+ $plugin->plugin_revoke ( { options ... } )
+ Called if the message is to be reported as ham (revokes a spam
+ report). If the reporting system is available, the variable
+ "$options-<gt"{revoke}-><gt>revoke_available}> should be set to 1;
+ if the reporting system successfully revoked the message, the
+ variable "$options-<gt"{revoke}-><gt>revoke_return}> should be set
+ to 1.
+
+ revoke
+ Reference to the Reporter object ("$options-<gt"{revoke}> in the
+ paragraph above.)
+
+ text
+ Reference to a markup removed copy of the message in scalar
+ string format.
+
+ msg Reference to the original message object.
+
+ $plugin->whitelist_address( { options ... } )
+ Called when a request is made to add an address to a persistent
+ address list.
+
+ address
+ Address you wish to add.
+
+ $plugin->blacklist_address( { options ... } )
+ Called when a request is made to add an address to a persistent
+ address list.
+
+ address
+ Address you wish to add.
+
+ $plugin->remove_address( { options ... } )
+ Called when a request is made to remove an address to a persistent
+ address list.
+
+ address
+ Address you wish to remove.
+
+ $plugin->spamd_child_init ()
+ Called when a new child starts up under spamd.
+
+ $plugin->spamd_child_post_connection_close ()
+ Called when child returns from handling a connection.
+
+ If there was an accept failure, the child will die and this code
+ will not be called.
+
+ $plugin->finish ()
+ Called when the "Mail::SpamAssassin" object is destroyed.
+
+HELPER APIS
+ These methods provide an API for plugins to register themselves to
+ receive specific events, or control the callback chain behaviour.
+
+ $plugin->register_eval_rule ($nameofevalsub)
+ Plugins that implement an eval test will need to call this, so that
+ SpamAssassin calls into the object when that eval test is
+ encountered. See the REGISTERING EVAL RULES section for full
+ details.
+
+ $plugin->inhibit_further_callbacks()
+ Tells the plugin handler to inhibit calling into other plugins in
+ the plugin chain for the current callback. Frequently used when
+ parsing configuration settings using "parse_config()".
+
+ dbg($message)
+ Output a debugging message $message, if the SpamAssassin object is
+ running with debugging turned on.
+
+ *NOTE:* This function is not available in the package namespace of
+ general plugins and can't be called via $self->dbg(). If a plugin
+ wishes to output debug information, it should call
+ "Mail::SpamAssassin::Plugin::dbg($msg)".
+
+ info($message)
+ Output an informational message $message, if the SpamAssassin object
+ is running with informational messages turned on.
+
+ *NOTE:* This function is not available in the package namespace of
+ general plugins and can't be called via $self->dbg(). If a plugin
+ wishes to output debug information, it should call
+ "Mail::SpamAssassin::Plugin::dbg($msg)".
+
+REGISTERING EVAL RULES
+ Plugins that implement an eval test must register the methods that can
+ be called from rules in the configuration files, in the plugin class'
+ constructor.
+
+ For example,
+
+ $plugin->register_eval_rule ('check_for_foo')
+
+ will cause "$plugin->check_for_foo()" to be called for this SpamAssassin
+ rule:
+
+ header FOO_RULE eval:check_for_foo()
+
+ Note that eval rules are passed the following arguments:
+
+ - The plugin object itself
+ - The "Mail::SpamAssassin::PerMsgStatus" object calling the rule
+ - standard arguments for the rule type in use
+ - any and all arguments as specified in the configuration file
+
+ In other words, the eval test method should look something like this:
+
+ sub check_for_foo {
+ my ($self, $permsgstatus, ...arguments...) = @_;
+ ...code returning 0 or 1
+ }
+
+ Note that the headers can be accessed using the "get()" method on the
+ "Mail::SpamAssassin::PerMsgStatus" object, and the body by
+ "get_decoded_stripped_body_text_array()" and other similar methods.
+ Similarly, the "Mail::SpamAssassin::Conf" object holding the current
+ configuration may be accessed through "$permsgstatus->{main}->{conf}".
+
+ The eval rule should return 1 for a hit, or 0 if the rule is not hit.
+
+ State for a single message being scanned should be stored on the
+ $checker object, not on the $self object, since $self persists between
+ scan operations. See the 'lifecycle note' on the "check_start()" method
+ above.
+
+STANDARD ARGUMENTS FOR RULE TYPES
+ Plugins will be called with the same arguments as a standard EvalTest.
+ Different rule types receive different information by default:
+
+ - header tests: no extra arguments
+ - body tests: fully rendered message as array reference
+ - rawbody tests: fully decoded message as array reference
+ - full tests: pristine message as scalar reference
+
+ The configuration file arguments will be passed in after the standard
+ arguments.
+
+SEE ALSO
+ "Mail::SpamAssassin"
+
+ "Mail::SpamAssassin::PerMsgStatus"
+
+ http://wiki.apache.org/spamassassin/PluginWritingTips
+
+ http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163
+
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.html?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.html (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.html Mon Oct 16 08:57:50 2006
@@ -0,0 +1,27 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PluginHandler - SpamAssassin plugin handler</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PluginHandler - SpamAssassin plugin handler</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.txt?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.txt (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_PluginHandler.txt Mon Oct 16 08:57:50 2006
@@ -0,0 +1,3 @@
+NAME
+ Mail::SpamAssassin::PluginHandler - SpamAssassin plugin handler
+
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.html?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.html (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.html Mon Oct 16 08:57:50 2006
@@ -0,0 +1,226 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Plugin::AWL - Normalize scores via auto-whitelist</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#template_tags">TEMPLATE TAGS</a></li>
+ <li><a href="#user_preferences">USER PREFERENCES</a></li>
+ <li><a href="#administrator_settings">ADMINISTRATOR SETTINGS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::AWL - Normalize scores via auto-whitelist</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>To try this out, add this or uncomment this line in init.pre:</p>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::AWL</pre>
+<p>Use the supplied 60_awl.cf file (ie you don't have to do anything) or
+add these lines to a .cf file:</p>
+<pre>
+ header AWL eval:check_from_in_auto_whitelist()
+ describe AWL From: address is in the auto white-list
+ tflags AWL userconf noautolearn
+ priority AWL 1000</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This plugin module provides support for the auto-whitelist. It keeps
+track of the average SpamAssassin score for senders. Senders are
+tracked using a combination of their From: address and their IP address.
+It then uses that average score to reduce the variability in scoring
+from message to message and modifies the final score by pushing the
+result towards the historical average. This improves the accuracy of
+filtering for most email.</p>
+<p>
+</p>
+<hr />
+<h1><a name="template_tags">TEMPLATE TAGS</a></h1>
+<p>This plugin module adds the following <code>tags</code> that can be used as
+placeholders in certain options. See <code>Mail::SpamAssassin::Conf</code>
+for more information on TEMPLATE TAGS.</p>
+<pre>
+ _AWL_ AWL modifier
+ _AWLMEAN_ Mean score on which AWL modification is based
+ _AWLCOUNT_ Number of messages on which AWL modification is based
+ _AWLPRESCORE_ Score before AWL</pre>
+<p>
+</p>
+<hr />
+<h1><a name="user_preferences">USER PREFERENCES</a></h1>
+<p>The following options can be used in both site-wide (<code>local.cf</code>) and
+user-specific (<code>user_prefs</code>) configuration files to customize how
+SpamAssassin handles incoming email messages.</p>
+<dl>
+<dt><strong><a name="item_use_auto_whitelist">use_auto_whitelist ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether to use auto-whitelists. Auto-whitelists track the long-term
+average score for each sender and then shift the score of new messages
+toward that long-term average. This can increase or decrease the score
+for messages, depending on the long-term behavior of the particular
+correspondent.
+</dd>
+<dd>
+<p>For more information about the auto-whitelist system, please look
+at the the <code>Automatic Whitelist System</code> section of the README file.
+The auto-whitelist is not intended as a general-purpose replacement
+for static whitelist entries added to your config files.</p>
+</dd>
+<dd>
+<p>Note that certain tests are ignored when determining the final
+message score:</p>
+</dd>
+<dd>
+<pre>
+ - rules with tflags set to 'noautolearn'</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_n">auto_whitelist_factor n (default: 0.5, range [0..1])</a></strong><br />
+</dt>
+<dd>
+How much towards the long-term mean for the sender to regress a message.
+Basically, the algorithm is to track the long-term mean score of messages for
+the sender (<code>mean</code>), and then once we have otherwise fully calculated the
+score for this message (<code>score</code>), we calculate the final score for the
+message as:
+</dd>
+<dd>
+<p><code>finalscore</code> = <code>score</code> + (<code>mean</code> - <code>score</code>) * <code>factor</code></p>
+</dd>
+<dd>
+<p>So if <code>factor</code> = 0.5, then we'll move to half way between the calculated
+score and the mean. If <code>factor</code> = 0.3, then we'll move about 1/3 of the way
+from the score toward the mean. <code>factor</code> = 1 means just use the long-term
+mean; <code>factor</code> = 0 mean just use the calculated score.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_user_awl_sql_override_username">user_awl_sql_override_username</a></strong><br />
+</dt>
+<dd>
+Used by the SQLBasedAddrList storage implementation.
+</dd>
+<dd>
+<p>If this option is set the SQLBasedAddrList module will override the set
+username with the value given. This can be useful for implementing global
+or group based auto-whitelist databases.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="administrator_settings">ADMINISTRATOR SETTINGS</a></h1>
+<p>These settings differ from the ones above, in that they are considered 'more
+privileged' -- even more than the ones in the <strong>PRIVILEGED SETTINGS</strong> section.
+No matter what <code>allow_user_rules</code> is set to, these can never be set from a
+user's <code>user_prefs</code> file.</p>
+<dl>
+<dt><strong><a name="item_module">auto_whitelist_factory module (default: Mail::SpamAssassin::DBBasedAddrList)</a></strong><br />
+</dt>
+<dd>
+Select alternative whitelist factory module.
+</dd>
+<p></p>
+<dt><strong><a name="item_filename">auto_whitelist_path /path/filename (default: ~/.spamassassin/auto-whitelist)</a></strong><br />
+</dt>
+<dd>
+This is the automatic-whitelist directory and filename. By default, each user
+has their own whitelist database in their <code>~/.spamassassin</code> directory with
+mode 0700. For system-wide SpamAssassin use, you may want to share this
+across all users, although that is not recommended.
+</dd>
+<p></p>
+<dt><strong><a name="item_auto_whitelist_db_modules_module__2e_2e_2e__28defa">auto_whitelist_db_modules Module ... (default: see below)</a></strong><br />
+</dt>
+<dd>
+What database modules should be used for the auto-whitelist storage database
+file. The first named module that can be loaded from the perl include path
+will be used. The format is:
+</dd>
+<dd>
+<pre>
+ PreferredModuleName SecondBest ThirdBest ...</pre>
+</dd>
+<dd>
+<p>ie. a space-separated list of perl module names. The default is:</p>
+</dd>
+<dd>
+<pre>
+ DB_File GDBM_File SDBM_File</pre>
+</dd>
+<dd>
+<p>NDBM_File is no longer supported, since it appears to have bugs that
+preclude its use for the AWL (see SpamAssassin bug 4353).</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_auto_whitelist_file_mode">auto_whitelist_file_mode (default: 0600)</a></strong><br />
+</dt>
+<dd>
+The file mode bits used for the automatic-whitelist directory or file.
+</dd>
+<dd>
+<p>Make sure you specify this using the 'x' mode bits set, as it may also be used
+to create directories. However, if a file is created, the resulting file will
+not have any execute bits set (the umask is set to 111).</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_user_awl_dsn_dbi_3adatabasetype_3adatabasename_3ah">user_awl_dsn DBI:databasetype:databasename:hostname:port</a></strong><br />
+</dt>
+<dd>
+Used by the SQLBasedAddrList storage implementation.
+</dd>
+<dd>
+<p>This will set the DSN used to connect. Example:
+<code>DBI:mysql:spamassassin:localhost</code></p>
+</dd>
+<p></p>
+<dt><strong><a name="item_user_awl_sql_username_username">user_awl_sql_username username</a></strong><br />
+</dt>
+<dd>
+Used by the SQLBasedAddrList storage implementation.
+</dd>
+<dd>
+<p>The authorized username to connect to the above DSN.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_user_awl_sql_password_password">user_awl_sql_password password</a></strong><br />
+</dt>
+<dd>
+Used by the SQLBasedAddrList storage implementation.
+</dd>
+<dd>
+<p>The password for the database username, for the above DSN.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_user_awl_sql_table_tablename">user_awl_sql_table tablename</a></strong><br />
+</dt>
+<dd>
+Used by the SQLBasedAddrList storage implementation.
+</dd>
+<dd>
+<p>The table user auto-whitelists are stored in, for the above DSN.</p>
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.txt?view=auto&rev=464529
==============================================================================
--- spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.txt (added)
+++ spamassassin/site/full/3.1.x/doc/Mail_SpamAssassin_Plugin_AWL.txt Mon Oct 16 08:57:50 2006
@@ -0,0 +1,141 @@
+NAME
+ Mail::SpamAssassin::Plugin::AWL - Normalize scores via auto-whitelist
+
+SYNOPSIS
+ To try this out, add this or uncomment this line in init.pre:
+
+ loadplugin Mail::SpamAssassin::Plugin::AWL
+
+ Use the supplied 60_awl.cf file (ie you don't have to do anything) or
+ add these lines to a .cf file:
+
+ header AWL eval:check_from_in_auto_whitelist()
+ describe AWL From: address is in the auto white-list
+ tflags AWL userconf noautolearn
+ priority AWL 1000
+
+DESCRIPTION
+ This plugin module provides support for the auto-whitelist. It keeps
+ track of the average SpamAssassin score for senders. Senders are tracked
+ using a combination of their From: address and their IP address. It then
+ uses that average score to reduce the variability in scoring from
+ message to message and modifies the final score by pushing the result
+ towards the historical average. This improves the accuracy of filtering
+ for most email.
+
+TEMPLATE TAGS
+ This plugin module adds the following "tags" that can be used as
+ placeholders in certain options. See "Mail::SpamAssassin::Conf" for more
+ information on TEMPLATE TAGS.
+
+ _AWL_ AWL modifier
+ _AWLMEAN_ Mean score on which AWL modification is based
+ _AWLCOUNT_ Number of messages on which AWL modification is based
+ _AWLPRESCORE_ Score before AWL
+
+USER PREFERENCES
+ The following options can be used in both site-wide ("local.cf") and
+ user-specific ("user_prefs") configuration files to customize how
+ SpamAssassin handles incoming email messages.
+
+ use_auto_whitelist ( 0 | 1 ) (default: 1)
+ Whether to use auto-whitelists. Auto-whitelists track the long-term
+ average score for each sender and then shift the score of new
+ messages toward that long-term average. This can increase or
+ decrease the score for messages, depending on the long-term behavior
+ of the particular correspondent.
+
+ For more information about the auto-whitelist system, please look at
+ the the "Automatic Whitelist System" section of the README file. The
+ auto-whitelist is not intended as a general-purpose replacement for
+ static whitelist entries added to your config files.
+
+ Note that certain tests are ignored when determining the final
+ message score:
+
+ - rules with tflags set to 'noautolearn'
+
+ auto_whitelist_factor n (default: 0.5, range [0..1])
+ How much towards the long-term mean for the sender to regress a
+ message. Basically, the algorithm is to track the long-term mean
+ score of messages for the sender ("mean"), and then once we have
+ otherwise fully calculated the score for this message ("score"), we
+ calculate the final score for the message as:
+
+ "finalscore" = "score" + ("mean" - "score") * "factor"
+
+ So if "factor" = 0.5, then we'll move to half way between the
+ calculated score and the mean. If "factor" = 0.3, then we'll move
+ about 1/3 of the way from the score toward the mean. "factor" = 1
+ means just use the long-term mean; "factor" = 0 mean just use the
+ calculated score.
+
+ user_awl_sql_override_username
+ Used by the SQLBasedAddrList storage implementation.
+
+ If this option is set the SQLBasedAddrList module will override the
+ set username with the value given. This can be useful for
+ implementing global or group based auto-whitelist databases.
+
+ADMINISTRATOR SETTINGS
+ These settings differ from the ones above, in that they are considered
+ 'more privileged' -- even more than the ones in the PRIVILEGED SETTINGS
+ section. No matter what "allow_user_rules" is set to, these can never be
+ set from a user's "user_prefs" file.
+
+ auto_whitelist_factory module (default:
+ Mail::SpamAssassin::DBBasedAddrList)
+ Select alternative whitelist factory module.
+
+ auto_whitelist_path /path/filename (default:
+ ~/.spamassassin/auto-whitelist)
+ This is the automatic-whitelist directory and filename. By default,
+ each user has their own whitelist database in their
+ "~/.spamassassin" directory with mode 0700. For system-wide
+ SpamAssassin use, you may want to share this across all users,
+ although that is not recommended.
+
+ auto_whitelist_db_modules Module ... (default: see below)
+ What database modules should be used for the auto-whitelist storage
+ database file. The first named module that can be loaded from the
+ perl include path will be used. The format is:
+
+ PreferredModuleName SecondBest ThirdBest ...
+
+ ie. a space-separated list of perl module names. The default is:
+
+ DB_File GDBM_File SDBM_File
+
+ NDBM_File is no longer supported, since it appears to have bugs that
+ preclude its use for the AWL (see SpamAssassin bug 4353).
+
+ auto_whitelist_file_mode (default: 0600)
+ The file mode bits used for the automatic-whitelist directory or
+ file.
+
+ Make sure you specify this using the 'x' mode bits set, as it may
+ also be used to create directories. However, if a file is created,
+ the resulting file will not have any execute bits set (the umask is
+ set to 111).
+
+ user_awl_dsn DBI:databasetype:databasename:hostname:port
+ Used by the SQLBasedAddrList storage implementation.
+
+ This will set the DSN used to connect. Example:
+ "DBI:mysql:spamassassin:localhost"
+
+ user_awl_sql_username username
+ Used by the SQLBasedAddrList storage implementation.
+
+ The authorized username to connect to the above DSN.
+
+ user_awl_sql_password password
+ Used by the SQLBasedAddrList storage implementation.
+
+ The password for the database username, for the above DSN.
+
+ user_awl_sql_table tablename
+ Used by the SQLBasedAddrList storage implementation.
+
+ The table user auto-whitelists are stored in, for the above DSN.
+