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 2007/05/02 14:33:14 UTC
svn commit: r534420 [8/13] - in /spamassassin/site/full/3.2.x: ./ doc/
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,706 @@
+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->compile_now_start ( { options ... } )
+ This is called at the beginning of Mail::SpamAssassin::compile_now()
+ so plugins can do any necessary initialization for multi-process
+ SpamAssassin (such as spamd or mass-check -j).
+
+ use_user_prefs
+ The value of $use_user_prefs option in compile_now().
+
+ keep_userstate
+ The value of $keep_userstate option in compile_now().
+
+ $plugin->compile_now_finish ( { options ... } )
+ This is called at the end of Mail::SpamAssassin::compile_now() so
+ plugins can do any necessary initialization for multi-process
+ SpamAssassin (such as spamd or mass-check -j).
+
+ use_user_prefs
+ The value of $use_user_prefs option in compile_now().
+
+ keep_userstate
+ The value of $keep_userstate option in compile_now().
+
+ $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->check_main ( { options ... } )
+ Signals that a message should be checked. Note that implementations
+ of this hook should return 1.
+
+ 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->finish_tests ( { options ... } )
+ Called via SpamAssassin::finish and should clear up any tests that a
+ plugin has added to the namespace.
+
+ In certain circumstances, plugins may find it useful to compile perl
+ functions from the ruleset, on the fly. It is important to remove
+ these once the "Mail::SpamAssassin" object is deleted, however, and
+ this API allows this.
+
+ Each plugin is responsible for its own generated perl functions.
+
+ conf
+ The "Mail::SpamAssassin::Conf" object on which the configuration
+ data should be stored.
+
+ $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->start_rules ( { options ... } )
+ Called before testing a set of rules of a given type and
+ priority.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for
+ this scan.
+
+ ruletype
+ The type of the rules about to be performed.
+
+ priority
+ The priority level of the rules about to be performed.
+
+ $plugin->hit_rule ( { options ... } )
+ Called when a rule fires.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for
+ this scan.
+
+ ruletype
+ The type of the rule that fired.
+
+ rulename
+ The name of the rule that fired.
+
+ score
+ The rule's score in the active scoreset.
+
+ $plugin->ran_rule ( { options ... } )
+ Called after a rule has been tested, whether or not it fired.
+ When the rule fires, the hit_rule callback is always called
+ before this.
+
+ permsgstatus
+ The "Mail::SpamAssassin::PerMsgStatus" context object for
+ this scan.
+
+ ruletype
+ The type of the rule that was tested.
+
+ rulename
+ The name of the rule that was tested.
+
+ $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->have_shortcircuited ( { options ... } )
+ Has the current scan operation 'short-circuited'? In other
+ words, can further scanning be skipped, since the message is
+ already definitively classified as either spam or ham?
+
+ Plugins should return 0 to indicate that scanning should
+ continue, or 1 to indicate that short-circuiting has taken
+ effect.
+
+ 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->log_scan_result ( { options ... } )
+ Called when spamd has completed scanning a message. Currently,
+ only spamd calls this API.
+
+ result
+ The 'result: ...' line for this scan. Format is as described
+ at http://wiki.apache.org/spamassassin/SpamdSyslogFormat.
+
+ $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->register_generated_rule_method ($nameofsub)
+ In certain circumstances, plugins may find it useful to compile
+ perl functions from the ruleset, on the fly. It is important to
+ remove these once the "Mail::SpamAssassin" object is deleted,
+ however, and this API allows this.
+
+ Once the method $nameofsub has been generated, call this API
+ with the name of the method (including full package scope). This
+ indicates that it's a temporary piece of generated code, built
+ from the SpamAssassin ruleset, and when
+ "Mail::SpamAssassin::finish()" is called, the method will be
+ destroyed.
+
+ This API was added in SpamAssassin 3.2.0.
+
+ $plugin->register_method_priority($methodname, $priority)
+ Indicate that the method named $methodname on the current object
+ has a callback priority of $priority.
+
+ This is used by the plugin handler to determine the relative
+ order of callbacks; plugins with lower-numbered priorities are
+ called before plugins with higher-numbered priorities. Each
+ method can have a different priority value. The default value is
+ 0. The ordering of callbacks to methods with equal priority is
+ undefined.
+
+ Typically, you only need to worry about this if you need to
+ ensure your plugin's method is called before another plugin's
+ implementation of that method. It should be called from your
+ plugin's constructor.
+
+ This API was added in SpamAssassin 3.2.0.
+
+ $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->info(). If a
+ plugin wishes to output debug information, it should call
+ "Mail::SpamAssassin::Plugin::info($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.
+
+BACKWARDS COMPATIBILITY
+ Note that if you write a plugin and need to determine if a
+ particular helper method is supported on
+ "Mail::SpamAssassin::Plugin", you can do this:
+
+ if ($self->can("name_of_method")) {
+ eval {
+ $self->name_of_method(); # etc.
+ }
+ } else {
+ # take fallback action
+ }
+
+ The same applies for the public APIs on objects of other types, such
+ as "Mail::SpamAssassin::PerMsgStatus".
+
+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.2.x/doc/Mail_SpamAssassin_PluginHandler.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.html Wed May 2 05:33:04 2007
@@ -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.2.x/doc/Mail_SpamAssassin_PluginHandler.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,3 @@
+NAME
+ Mail::SpamAssassin::PluginHandler - SpamAssassin plugin handler
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.html Wed May 2 05:33:04 2007
@@ -0,0 +1,140 @@
+<!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::ASN - SpamAssassin plugin to look up the Autonomous System Number of the connecting IP address.</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="#configuration">CONFIGURATION</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+ <li><a href="#status">STATUS</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::ASN - SpamAssassin plugin to look up the Autonomous System Number (ASN) of the connecting IP address.</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::ASN</pre>
+<pre>
+ asn_lookup asn.routeviews.org _ASN_ _ASNCIDR_</pre>
+<pre>
+ add_header all ASN _ASN_ _ASNCIDR_</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This plugin uses DNS lookups to the services of
+<code>http://www.routeviews.org/</code> to do the actual work. Please make sure
+that your use of the plugin does not overload their infrastructure -
+this generally means that <strong>you should not use this plugin in a
+high-volume environment</strong> or that you should use a local mirror of the
+zone (see <code>ftp://ftp.routeviews.org/dnszones/</code>).</p>
+<p>
+</p>
+<hr />
+<h1><a name="template_tags">TEMPLATE TAGS</a></h1>
+<p>This plugin allows you to create template tags containing the connecting
+IP's AS number and route info for that AS number.</p>
+<p>The default config will add a header that looks like this:</p>
+<pre>
+ X-Spam-ASN: AS24940 213.239.192.0/18</pre>
+<p>where ``AS24940'' is the ASN and ``213.239.192.0/18'' is the route
+announced by that ASN where the connecting IP address came from. If
+the AS announces multiple networks (more/less specific), they will
+all be added to the <code>_ASNCIDR_</code> tag, separated by spaces, eg:</p>
+<pre>
+ X-Spam-ASN: AS1680 89.138.0.0/15 89.139.0.0/16</pre>
+<p>
+</p>
+<hr />
+<h1><a name="configuration">CONFIGURATION</a></h1>
+<p>The standard ruleset contains a configuration that will add a header
+containing ASN data to scanned messages. The bayes tokenizer will use the
+added header for bayes calculations, and thus affect which BAYES_* rule will
+trigger for a particular message.</p>
+<p><strong>Note</strong> that in most cases you should not score on the ASN data directly.
+Bayes learning will probably trigger on the _ASNCIDR_ tag, but probably not
+very well on the _ASN_ tag alone.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><a href="http://www.routeviews.org/">http://www.routeviews.org/</a> - all data regarding routing, ASNs etc</p>
+<p><a href="http://issues.apache.org/SpamAssassin/show_bug.cgi?id=4770">http://issues.apache.org/SpamAssassin/show_bug.cgi?id=4770</a> -
+SpamAssassin Issue #4770 concerning this plugin</p>
+<p>
+</p>
+<hr />
+<h1><a name="status">STATUS</a></h1>
+<p>Experimental - Dec. 18, 2006</p>
+<p>No in-depth analysis of the usefulness of bayes tokenization of ASN data has
+been performed.</p>
+<p>
+</p>
+<hr />
+<h1><a name="administrator_settings">ADMINISTRATOR SETTINGS</a></h1>
+<dl>
+<dt><strong><a name="item_asn_lookup_asn_2dzone_2eexample_2ecom__5b__asntag_">asn_lookup asn-zone.example.com [ _ASNTAG_ _ASNCIDRTAG_ ]</a></strong><br />
+</dt>
+<dd>
+Use this to lookup the ASN info for first external IP address in the specified
+zone and add the AS number to the first specified tag and routing info to the
+second specified tag.
+</dd>
+<dd>
+<p>If no tags are specified the AS number will be added to the _ASN_ tag and the
+routing info will be added to the _ASNCIDR_ tag. You must specify either none
+or both of the tags. Tags must start and end with an underscore.</p>
+</dd>
+<dd>
+<p>If two or more <em>asn_lookup</em>s use the same set of template tags, the results of
+their lookups will be appended to each other in the template tag values in no
+particular order. Duplicate results will be omitted when combining results.
+In a similar fashion, you can also use the same template tag for both the AS
+number tag and the routing info tag.</p>
+</dd>
+<dd>
+<p>Examples:</p>
+</dd>
+<dd>
+<pre>
+ asn_lookup asn.routeviews.org</pre>
+</dd>
+<dd>
+<pre>
+ asn_lookup asn.routeviews.org _ASN_ _ASNCIDR_
+ asn_lookup myview.example.com _MYASN_ _MYASNCIDR_</pre>
+</dd>
+<dd>
+<pre>
+ asn_lookup asn.routeviews.org _COMBINEDASN_ _COMBINEDASNCIDR_
+ asn_lookup myview.example.com _COMBINEDASN_ _COMBINEDASNCIDR_</pre>
+</dd>
+<dd>
+<pre>
+ asn_lookup in1tag.example.net _ASNDATA_ _ASNDATA_</pre>
+</dd>
+</dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,86 @@
+NAME
+ Mail::SpamAssassin::Plugin::ASN - SpamAssassin plugin to look up the
+ Autonomous System Number (ASN) of the connecting IP address.
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::ASN
+
+ asn_lookup asn.routeviews.org _ASN_ _ASNCIDR_
+
+ add_header all ASN _ASN_ _ASNCIDR_
+
+DESCRIPTION
+ This plugin uses DNS lookups to the services of
+ "http://www.routeviews.org/" to do the actual work. Please make sure
+ that your use of the plugin does not overload their infrastructure -
+ this generally means that you should not use this plugin in a
+ high-volume environment or that you should use a local mirror of the
+ zone (see "ftp://ftp.routeviews.org/dnszones/").
+
+TEMPLATE TAGS
+ This plugin allows you to create template tags containing the connecting
+ IP's AS number and route info for that AS number.
+
+ The default config will add a header that looks like this:
+
+ X-Spam-ASN: AS24940 213.239.192.0/18
+
+ where "AS24940" is the ASN and "213.239.192.0/18" is the route announced
+ by that ASN where the connecting IP address came from. If the AS
+ announces multiple networks (more/less specific), they will all be added
+ to the "_ASNCIDR_" tag, separated by spaces, eg:
+
+ X-Spam-ASN: AS1680 89.138.0.0/15 89.139.0.0/16
+
+CONFIGURATION
+ The standard ruleset contains a configuration that will add a header
+ containing ASN data to scanned messages. The bayes tokenizer will use
+ the added header for bayes calculations, and thus affect which BAYES_*
+ rule will trigger for a particular message.
+
+ Note that in most cases you should not score on the ASN data directly.
+ Bayes learning will probably trigger on the _ASNCIDR_ tag, but probably
+ not very well on the _ASN_ tag alone.
+
+SEE ALSO
+ http://www.routeviews.org/ - all data regarding routing, ASNs etc
+
+ http://issues.apache.org/SpamAssassin/show_bug.cgi?id=4770 -
+ SpamAssassin Issue #4770 concerning this plugin
+
+STATUS
+ Experimental - Dec. 18, 2006
+
+ No in-depth analysis of the usefulness of bayes tokenization of ASN data
+ has been performed.
+
+ADMINISTRATOR SETTINGS
+ asn_lookup asn-zone.example.com [ _ASNTAG_ _ASNCIDRTAG_ ]
+ Use this to lookup the ASN info for first external IP address in the
+ specified zone and add the AS number to the first specified tag and
+ routing info to the second specified tag.
+
+ If no tags are specified the AS number will be added to the _ASN_
+ tag and the routing info will be added to the _ASNCIDR_ tag. You
+ must specify either none or both of the tags. Tags must start and
+ end with an underscore.
+
+ If two or more *asn_lookup*s use the same set of template tags, the
+ results of their lookups will be appended to each other in the
+ template tag values in no particular order. Duplicate results will
+ be omitted when combining results. In a similar fashion, you can
+ also use the same template tag for both the AS number tag and the
+ routing info tag.
+
+ Examples:
+
+ asn_lookup asn.routeviews.org
+
+ asn_lookup asn.routeviews.org _ASN_ _ASNCIDR_
+ asn_lookup myview.example.com _MYASN_ _MYASNCIDR_
+
+ asn_lookup asn.routeviews.org _COMBINEDASN_ _COMBINEDASNCIDR_
+ asn_lookup myview.example.com _COMBINEDASN_ _COMBINEDASNCIDR_
+
+ asn_lookup in1tag.example.net _ASNDATA_ _ASNDATA_
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.html Wed May 2 05:33:04 2007
@@ -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.2.x/doc/Mail_SpamAssassin_Plugin_AWL.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.txt Wed May 2 05:33:04 2007
@@ -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.
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html Wed May 2 05:33:04 2007
@@ -0,0 +1,57 @@
+<!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::AccessDB - check message against Access Database</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>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::AccessDB - check message against Access Database</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::AccessDB</pre>
+<pre>
+ header ACCESSDB eval:check_access_database('/etc/mail/access.db')
+ describe ACCESSDB Message would have been caught by accessdb
+ tflags ACCESSDB userconf
+ score ACCESSDB 2</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>Many MTAs support access databases, such as Sendmail, Postfix, etc.
+This plugin does similar checks to see whether a message would have
+been flagged.</p>
+<p>The rule returns false if an entry isn't found, or the entry has a RHS of
+<em>OK</em> or <em>SKIP</em>.</p>
+<p>The rule returns true if an entry exists and has a RHS of <em>REJECT</em>, <em>ERROR</em>,
+or <em>DISCARD</em>.</p>
+<p>Note: only the first word (split on non-word characters) of the RHS
+is checked, so <code>error:5.7.1:...</code> means <code>ERROR</code>.</p>
+<p><strong>AccessDB Pointers:</strong></p>
+<pre>
+ <a href="http://www.faqs.org/docs/securing/chap22sec178.html">http://www.faqs.org/docs/securing/chap22sec178.html</a>
+ <a href="http://www.postfix.org/access.5.html">http://www.postfix.org/access.5.html</a></pre>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,31 @@
+NAME
+ Mail::SpamAssassin::Plugin::AccessDB - check message against Access
+ Database
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::AccessDB
+
+ header ACCESSDB eval:check_access_database('/etc/mail/access.db')
+ describe ACCESSDB Message would have been caught by accessdb
+ tflags ACCESSDB userconf
+ score ACCESSDB 2
+
+DESCRIPTION
+ Many MTAs support access databases, such as Sendmail, Postfix, etc. This
+ plugin does similar checks to see whether a message would have been
+ flagged.
+
+ The rule returns false if an entry isn't found, or the entry has a RHS
+ of *OK* or *SKIP*.
+
+ The rule returns true if an entry exists and has a RHS of *REJECT*,
+ *ERROR*, or *DISCARD*.
+
+ Note: only the first word (split on non-word characters) of the RHS is
+ checked, so "error:5.7.1:..." means "ERROR".
+
+ AccessDB Pointers:
+
+ http://www.faqs.org/docs/securing/chap22sec178.html
+ http://www.postfix.org/access.5.html
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html Wed May 2 05:33:04 2007
@@ -0,0 +1,52 @@
+<!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>AntiVirus - simple anti-virus tests</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>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>AntiVirus - simple anti-virus tests</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::AntiVirus</pre>
+<pre>
+ body MICROSOFT_EXECUTABLE eval:check_microsoft_executable()
+ body MIME_SUSPECT_NAME eval:check_suspect_name()</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The MICROSOFT_EXECUTABLE rule works by checking for 3 possibilities in
+the message in any application/* or text/* part in the message:</p>
+<dl>
+<dt><strong><a name="item__2d_in_text_parts_2c_look_for_a_uuencoded_executab">- in text parts, look for a uuencoded executable start string</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_in_application_parts_2c_look_for_filenames_end">- in application parts, look for filenames ending in an executable extension</a></strong><br />
+</dt>
+<dt><strong><a name="item__2d_in_application_parts_2c_look_for_a_base64_enco">- in application parts, look for a base64 encoded executable start string</a></strong><br />
+</dt>
+</dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,19 @@
+NAME
+ AntiVirus - simple anti-virus tests
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::AntiVirus
+
+ body MICROSOFT_EXECUTABLE eval:check_microsoft_executable()
+ body MIME_SUSPECT_NAME eval:check_suspect_name()
+
+DESCRIPTION
+ The MICROSOFT_EXECUTABLE rule works by checking for 3 possibilities in
+ the message in any application/* or text/* part in the message:
+
+ - in text parts, look for a uuencoded executable start string
+ - in application parts, look for filenames ending in an executable
+ extension
+ - in application parts, look for a base64 encoded executable start
+ string
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html Wed May 2 05:33:04 2007
@@ -0,0 +1,82 @@
+<!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::AutoLearnThreshold - threshold-based discriminator for Bayes auto-learning</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="#user_options">USER OPTIONS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::AutoLearnThreshold - threshold-based discriminator for Bayes auto-learning</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::AutoLearnThreshold</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This plugin implements the threshold-based auto-learning discriminator
+for SpamAssassin's Bayes subsystem. Auto-learning is a mechanism
+whereby high-scoring mails (or low-scoring mails, for non-spam) are fed
+into its learning systems without user intervention, during scanning.</p>
+<p>Note that certain tests are ignored when determining whether a message
+should be trained upon:</p>
+<ul>
+<li><strong><a name="item_rules_with_tflags_set_to__27learn_27__28the_bayesi">rules with tflags set to 'learn' (the Bayesian rules)</a></strong><br />
+</li>
+<li><strong><a name="item_rules_with_tflags_set_to__27userconf_27__28user_co">rules with tflags set to 'userconf' (user configuration)</a></strong><br />
+</li>
+<li><strong><a name="item_rules_with_tflags_set_to__27noautolearn_27">rules with tflags set to 'noautolearn'</a></strong><br />
+</li>
+</ul>
+<p>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.</p>
+<p>
+</p>
+<hr />
+<h1><a name="user_options">USER OPTIONS</a></h1>
+<p>The following configuration settings are used to control auto-learning:</p>
+<dl>
+<dt><strong><a name="item_nn">bayes_auto_learn_threshold_nonspam n.nn (default: 0.1)</a></strong><br />
+</dt>
+<dd>
+The score threshold below which a mail has to score, to be fed into
+SpamAssassin's learning systems automatically as a non-spam message.
+</dd>
+<p></p>
+<dt><strong>bayes_auto_learn_threshold_spam n.nn (default: 12.0)</strong><br />
+</dt>
+<dd>
+The score threshold above which a mail has to score, to be fed into
+SpamAssassin's learning systems automatically as a spam message.
+</dd>
+<dd>
+<p>Note: SpamAssassin requires at least 3 points from the header, and 3
+points from the body to auto-learn as spam. Therefore, the minimum
+working value for this option is 6.</p>
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,39 @@
+NAME
+ Mail::SpamAssassin::Plugin::AutoLearnThreshold - threshold-based
+ discriminator for Bayes auto-learning
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::AutoLearnThreshold
+
+DESCRIPTION
+ This plugin implements the threshold-based auto-learning discriminator
+ for SpamAssassin's Bayes subsystem. Auto-learning is a mechanism whereby
+ high-scoring mails (or low-scoring mails, for non-spam) are fed into its
+ learning systems without user intervention, during scanning.
+
+ Note that certain tests are ignored when determining whether a message
+ should be trained upon:
+
+ * rules with tflags set to 'learn' (the Bayesian rules)
+ * rules with tflags set to 'userconf' (user configuration)
+ * 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.
+
+USER OPTIONS
+ The following configuration settings are used to control auto-learning:
+
+ bayes_auto_learn_threshold_nonspam n.nn (default: 0.1)
+ The score threshold below which a mail has to score, to be fed into
+ SpamAssassin's learning systems automatically as a non-spam message.
+
+ bayes_auto_learn_threshold_spam n.nn (default: 12.0)
+ The score threshold above which a mail has to score, to be fed into
+ SpamAssassin's learning systems automatically as a spam message.
+
+ Note: SpamAssassin requires at least 3 points from the header, and 3
+ points from the body to auto-learn as spam. Therefore, the minimum
+ working value for this option is 6.
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html Wed May 2 05:33:04 2007
@@ -0,0 +1,34 @@
+<!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::BodyRuleBaseExtractor - extract "bases" from body ruleset</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>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::BodyRuleBaseExtractor - extract ``bases'' from body ruleset</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>This is a plugin to extract ``base'' strings from SpamAssassin 'body' rules,
+suitable for use in Rule2XSBody rules or other parallel matching algorithms.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,9 @@
+NAME
+ Mail::SpamAssassin::Plugin::BodyRuleBaseExtractor - extract "bases" from
+ body ruleset
+
+SYNOPSIS
+ This is a plugin to extract "base" strings from SpamAssassin 'body'
+ rules, suitable for use in Rule2XSBody rules or other parallel matching
+ algorithms.
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.html Wed May 2 05:33:04 2007
@@ -0,0 +1,39 @@
+<!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>lib/Mail/SpamAssassin/Plugin/Check.pm</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>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::Check</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>loadplugin Mail::SpamAssassin::Plugin::Check</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This plugin provides the primary message check functionality.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,9 @@
+NAME
+ Mail::SpamAssassin::Plugin::Check
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::Check
+
+DESCRIPTION
+ This plugin provides the primary message check functionality.
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.html Wed May 2 05:33:04 2007
@@ -0,0 +1,142 @@
+<!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::DCC - perform DCC check of messages</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="#user_options">USER OPTIONS</a></li>
+ <li><a href="#administrator_options">ADMINISTRATOR OPTIONS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Plugin::DCC - perform DCC check of messages</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::DCC</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The DCC or Distributed Checksum Clearinghouse is a system of servers
+collecting and counting checksums of millions of mail messages. The
+counts can be used by SpamAssassin to detect and reject or filter spam.</p>
+<p>Because simplistic checksums of spam can be easily defeated, the main
+DCC checksums are fuzzy and ignore aspects of messages. The fuzzy
+checksums are changed as spam evolves.</p>
+<p>Note that DCC is disabled by default in <code>init.pre</code> because it is not
+open source. See the DCC license for more details.</p>
+<p>See <a href="http://www.rhyolite.com/anti-spam/dcc/">http://www.rhyolite.com/anti-spam/dcc/</a> for more information about
+DCC.</p>
+<p>
+</p>
+<hr />
+<h1><a name="user_options">USER OPTIONS</a></h1>
+<dl>
+<dt><strong><a name="item_use_dcc">use_dcc (0|1) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether to use DCC, if it is available.
+</dd>
+<p></p>
+<dt><strong><a name="item_dcc_body_max_number">dcc_body_max NUMBER</a></strong><br />
+</dt>
+<dt><strong><a name="item_dcc_fuz1_max_number">dcc_fuz1_max NUMBER</a></strong><br />
+</dt>
+<dt><strong><a name="item_dcc_fuz2_max_number">dcc_fuz2_max NUMBER</a></strong><br />
+</dt>
+<dd>
+This option sets how often a message's body/fuz1/fuz2 checksum must have been
+reported to the DCC server before SpamAssassin will consider the DCC check as
+matched.
+</dd>
+<dd>
+<p>As nearly all DCC clients are auto-reporting these checksums, you should set
+this to a relatively high value, e.g. <code>999999</code> (this is DCC's MANY count).</p>
+</dd>
+<dd>
+<p>The default is <code>999999</code> for all these options.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="administrator_options">ADMINISTRATOR OPTIONS</a></h1>
+<dl>
+<dt><strong><a name="item_n">dcc_timeout n (default: 8)</a></strong><br />
+</dt>
+<dd>
+How many seconds you wait for DCC to complete, before scanning continues
+without the DCC results.
+</dd>
+<p></p>
+<dt><strong><a name="item_dcc_home_string">dcc_home STRING</a></strong><br />
+</dt>
+<dd>
+This option tells SpamAssassin specifically where to find the dcc homedir.
+If <code>dcc_path</code> is not specified, it will default to looking in
+<code>dcc_home/bin</code> for dcc client instead of relying on SpamAssassin to find it
+in the current PATH. If it isn't found there, it will look in the current
+PATH. If a <code>dccifd</code> socket is found in <code>dcc_home</code>, it will use that
+interface that instead of <code>dccproc</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_dcc_dccifd_path_string">dcc_dccifd_path STRING</a></strong><br />
+</dt>
+<dd>
+This option tells SpamAssassin specifically where to find the dccifd socket.
+If <code>dcc_dccifd_path</code> is not specified, it will default to looking in
+<code>dcc_home</code> If a <code>dccifd</code> socket is found, it will use it instead of
+<code>dccproc</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_dcc_path_string">dcc_path STRING</a></strong><br />
+</dt>
+<dd>
+This option tells SpamAssassin specifically where to find the <code>dccproc</code>
+client instead of relying on SpamAssassin to find it in the current PATH.
+Note that if <em>taint mode</em> is enabled in the Perl interpreter, you should
+use this, as the current PATH will have been cleared.
+</dd>
+<p></p>
+<dt><strong><a name="item_dcc_options_options">dcc_options options</a></strong><br />
+</dt>
+<dd>
+Specify additional options to the <code>dccproc(8)</code> command. Please note that only
+characters in the range [0-9A-Za-z ,._/-] are allowed for security reasons.
+</dd>
+<dd>
+<p>The default is <code>undef</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dccifd_options_options">dccifd_options options</a></strong><br />
+</dt>
+<dd>
+Specify additional options to send to the <code>dccifd(8)</code> daemon. Please note that only
+characters in the range [0-9A-Za-z ,._/-] are allowed for security reasons.
+</dd>
+<dd>
+<p>The default is <code>undef</code>.</p>
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,78 @@
+NAME
+ Mail::SpamAssassin::Plugin::DCC - perform DCC check of messages
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::DCC
+
+DESCRIPTION
+ The DCC or Distributed Checksum Clearinghouse is a system of servers
+ collecting and counting checksums of millions of mail messages. The
+ counts can be used by SpamAssassin to detect and reject or filter spam.
+
+ Because simplistic checksums of spam can be easily defeated, the main
+ DCC checksums are fuzzy and ignore aspects of messages. The fuzzy
+ checksums are changed as spam evolves.
+
+ Note that DCC is disabled by default in "init.pre" because it is not
+ open source. See the DCC license for more details.
+
+ See http://www.rhyolite.com/anti-spam/dcc/ for more information about
+ DCC.
+
+USER OPTIONS
+ use_dcc (0|1) (default: 1)
+ Whether to use DCC, if it is available.
+
+ dcc_body_max NUMBER
+ dcc_fuz1_max NUMBER
+ dcc_fuz2_max NUMBER
+ This option sets how often a message's body/fuz1/fuz2 checksum must
+ have been reported to the DCC server before SpamAssassin will
+ consider the DCC check as matched.
+
+ As nearly all DCC clients are auto-reporting these checksums, you
+ should set this to a relatively high value, e.g. 999999 (this is
+ DCC's MANY count).
+
+ The default is 999999 for all these options.
+
+ADMINISTRATOR OPTIONS
+ dcc_timeout n (default: 8)
+ How many seconds you wait for DCC to complete, before scanning
+ continues without the DCC results.
+
+ dcc_home STRING
+ This option tells SpamAssassin specifically where to find the dcc
+ homedir. If "dcc_path" is not specified, it will default to looking
+ in "dcc_home/bin" for dcc client instead of relying on SpamAssassin
+ to find it in the current PATH. If it isn't found there, it will
+ look in the current PATH. If a "dccifd" socket is found in
+ "dcc_home", it will use that interface that instead of "dccproc".
+
+ dcc_dccifd_path STRING
+ This option tells SpamAssassin specifically where to find the dccifd
+ socket. If "dcc_dccifd_path" is not specified, it will default to
+ looking in "dcc_home" If a "dccifd" socket is found, it will use it
+ instead of "dccproc".
+
+ dcc_path STRING
+ This option tells SpamAssassin specifically where to find the
+ "dccproc" client instead of relying on SpamAssassin to find it in
+ the current PATH. Note that if *taint mode* is enabled in the Perl
+ interpreter, you should use this, as the current PATH will have been
+ cleared.
+
+ dcc_options options
+ Specify additional options to the dccproc(8) command. Please note
+ that only characters in the range [0-9A-Za-z ,._/-] are allowed for
+ security reasons.
+
+ The default is "undef".
+
+ dccifd_options options
+ Specify additional options to send to the dccifd(8) daemon. Please
+ note that only characters in the range [0-9A-Za-z ,._/-] are allowed
+ for security reasons.
+
+ The default is "undef".
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.html?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.html Wed May 2 05:33:04 2007
@@ -0,0 +1,125 @@
+<!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::DKIM - perform DKIM verification tests</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="#see_also">SEE ALSO</a></li>
+ <li><a href="#user_settings">USER SETTINGS</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::DKIM - perform DKIM verification tests</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ loadplugin Mail::SpamAssassin::Plugin::DKIM [/path/to/DKIM.pm]</pre>
+<pre>
+ full DOMAINKEY_DOMAIN eval:check_dkim_verified()</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This SpamAssassin plugin implements DKIM lookups as described by the current
+draft specs: draft-ietf-dkim-base-10, as well as DomainKeys lookups, as
+described in draft-delany-domainkeys-base-06, thanks to the support for both
+types of signatures by newer versions of module Mail::DKIM (0.22 or later).</p>
+<p>It requires the <code>Mail::DKIM</code> CPAN module to operate. Many thanks to Jason Long
+for that module.</p>
+<p>Note that if <code>Mail::DKIM</code> version 0.20 or later is installed, this plugin will
+also perform Domain Key lookups on DomainKey-Signature headers.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::DKIM</code>, <code>Mail::SpamAssassin::Plugin</code></p>
+<pre>
+ <a href="http://jason.long.name/dkimproxy/">http://jason.long.name/dkimproxy/</a></pre>
+<p>
+</p>
+<hr />
+<h1><a name="user_settings">USER SETTINGS</a></h1>
+<dl>
+<dt><strong><a name="item_whitelist_from_dkim_add_40ress_2ecom__5bidentity_5">whitelist_from_dkim <a href="mailto:add@ress.com">add@ress.com</a> [identity]</a></strong><br />
+</dt>
+<dd>
+Use this to supplement the whitelist_from addresses with a check to make sure
+the message has been signed by a Domain Keys Identified Mail (DKIM) signature
+that can be verified against the From: domain's DKIM public key.
+</dd>
+<dd>
+<p>In order to support optional identities, only one whitelist entry is allowed
+per line, exactly like <code>whitelist_from_rcvd</code>. Multiple <code>whitelist_from_dkim</code>
+lines are allowed. File-glob style meta characters are allowed for the From:
+address, just like with <code>whitelist_from_rcvd</code>. The optional identity
+parameter must match from the right-most side, also like in
+<code>whitelist_from_rcvd</code>.</p>
+</dd>
+<dd>
+<p>If no identity parameter is specified the domain of the address parameter
+specified will be used instead.</p>
+</dd>
+<dd>
+<p>The From: address is obtained from a signed part of the message (ie. the
+``From:'' header), not from envelope data that is possible to forge.</p>
+</dd>
+<dd>
+<p>Since this whitelist requires an DKIM check to be made, network tests must be
+enabled.</p>
+</dd>
+<dd>
+<p>Examples:</p>
+</dd>
+<dd>
+<pre>
+ whitelist_from_dkim joe@example.com
+ whitelist_from_dkim *@corp.example.com</pre>
+</dd>
+<dd>
+<pre>
+ whitelist_from_dkim jane@example.net example.org
+ whitelist_from_dkim dick@example.net richard@example.net</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_def_whitelist_from_dkim_add_40ress_2ecom__5bidenti">def_whitelist_from_dkim <a href="mailto:add@ress.com">add@ress.com</a> [identity]</a></strong><br />
+</dt>
+<dd>
+Same as <code>whitelist_from_dkim</code>, but used for the default whitelist entries
+in the SpamAssassin distribution. The whitelist score is lower, because
+these are often targets for spammer spoofing.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="administrator_settings">ADMINISTRATOR SETTINGS</a></h1>
+<dl>
+<dt><strong><a name="item_n">dkim_timeout n (default: 5)</a></strong><br />
+</dt>
+<dd>
+How many seconds to wait for a DKIM query to complete, before
+scanning continues without the DKIM result.
+</dd>
+</dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt?view=auto&rev=534420
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt Wed May 2 05:33:04 2007
@@ -0,0 +1,69 @@
+NAME
+ Mail::SpamAssassin::Plugin::DKIM - perform DKIM verification tests
+
+SYNOPSIS
+ loadplugin Mail::SpamAssassin::Plugin::DKIM [/path/to/DKIM.pm]
+
+ full DOMAINKEY_DOMAIN eval:check_dkim_verified()
+
+DESCRIPTION
+ This SpamAssassin plugin implements DKIM lookups as described by the
+ current draft specs: draft-ietf-dkim-base-10, as well as DomainKeys
+ lookups, as described in draft-delany-domainkeys-base-06, thanks to the
+ support for both types of signatures by newer versions of module
+ Mail::DKIM (0.22 or later).
+
+ It requires the "Mail::DKIM" CPAN module to operate. Many thanks to
+ Jason Long for that module.
+
+ Note that if "Mail::DKIM" version 0.20 or later is installed, this
+ plugin will also perform Domain Key lookups on DomainKey-Signature
+ headers.
+
+SEE ALSO
+ "Mail::DKIM", "Mail::SpamAssassin::Plugin"
+
+ http://jason.long.name/dkimproxy/
+
+USER SETTINGS
+ whitelist_from_dkim add@ress.com [identity]
+ Use this to supplement the whitelist_from addresses with a check to
+ make sure the message has been signed by a Domain Keys Identified
+ Mail (DKIM) signature that can be verified against the From:
+ domain's DKIM public key.
+
+ In order to support optional identities, only one whitelist entry is
+ allowed per line, exactly like "whitelist_from_rcvd". Multiple
+ "whitelist_from_dkim" lines are allowed. File-glob style meta
+ characters are allowed for the From: address, just like with
+ "whitelist_from_rcvd". The optional identity parameter must match
+ from the right-most side, also like in "whitelist_from_rcvd".
+
+ If no identity parameter is specified the domain of the address
+ parameter specified will be used instead.
+
+ The From: address is obtained from a signed part of the message (ie.
+ the "From:" header), not from envelope data that is possible to
+ forge.
+
+ Since this whitelist requires an DKIM check to be made, network
+ tests must be enabled.
+
+ Examples:
+
+ whitelist_from_dkim joe@example.com
+ whitelist_from_dkim *@corp.example.com
+
+ whitelist_from_dkim jane@example.net example.org
+ whitelist_from_dkim dick@example.net richard@example.net
+
+ def_whitelist_from_dkim add@ress.com [identity]
+ Same as "whitelist_from_dkim", but used for the default whitelist
+ entries in the SpamAssassin distribution. The whitelist score is
+ lower, because these are often targets for spammer spoofing.
+
+ADMINISTRATOR SETTINGS
+ dkim_timeout n (default: 5)
+ How many seconds to wait for a DKIM query to complete, before
+ scanning continues without the DKIM result.
+