You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by qu...@apache.org on 2005/03/12 01:48:27 UTC
svn commit: r157194 - in spamassassin/trunk: MANIFEST Makefile.PL
sa-filter.raw spamassassin-script.pod spamassassin.raw
Author: quinlan
Date: Fri Mar 11 16:48:25 2005
New Revision: 157194
URL: http://svn.apache.org/viewcvs?view=rev&rev=157194
Log:
move sa-filter.raw back to spamassassin.raw
in new spamassassin.raw, restore meta-document
move spamassassin.raw script usage to spamassassin-script.pod
Added:
spamassassin/trunk/spamassassin-script.pod
spamassassin/trunk/spamassassin.raw
- copied, changed from r157182, spamassassin/trunk/sa-filter.raw
Removed:
spamassassin/trunk/sa-filter.raw
Modified:
spamassassin/trunk/MANIFEST
spamassassin/trunk/Makefile.PL
Modified: spamassassin/trunk/MANIFEST
URL: http://svn.apache.org/viewcvs/spamassassin/trunk/MANIFEST?view=diff&r1=157193&r2=157194
==============================================================================
--- spamassassin/trunk/MANIFEST (original)
+++ spamassassin/trunk/MANIFEST Fri Mar 11 16:48:25 2005
@@ -184,10 +184,10 @@
rules/name-triplets.txt
rules/triplets.txt
rules/user_prefs.template
-spamassassin.raw
-sa-filter.raw
sa-learn.raw
sa-update.raw
+spamassassin-script.pod
+spamassassin.raw
sample-nonspam.txt
sample-spam.txt
spamassassin.spec
Modified: spamassassin/trunk/Makefile.PL
URL: http://svn.apache.org/viewcvs/spamassassin/trunk/Makefile.PL?view=diff&r1=157193&r2=157194
==============================================================================
--- spamassassin/trunk/Makefile.PL (original)
+++ spamassassin/trunk/Makefile.PL Fri Mar 11 16:48:25 2005
@@ -165,7 +165,7 @@
},
'MAN1PODS' => {
- 'spamassassin' => '$(INST_MAN1DIR)/spamassassin.$(MAN1EXT)',
+ 'spamassassin-script.pod' => '$(INST_MAN1DIR)/spamassassin-script.$(MAN1EXT)',
'sa-learn' => '$(INST_MAN1DIR)/sa-learn.$(MAN1EXT)',
'sa-update' => '$(INST_MAN1DIR)/sa-update.$(MAN1EXT)',
'spamc/spamc.pod' => '$(INST_MAN1DIR)/spamc.$(MAN1EXT)',
Added: spamassassin/trunk/spamassassin-script.pod
URL: http://svn.apache.org/viewcvs/spamassassin/trunk/spamassassin-script.pod?view=auto&rev=157194
==============================================================================
--- spamassassin/trunk/spamassassin-script.pod (added)
+++ spamassassin/trunk/spamassassin-script.pod Fri Mar 11 16:48:25 2005
@@ -0,0 +1,292 @@
+=cut
+
+<@LICENSE>
+Copyright 2004 Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+</...@LICENSE>
+
+=head1 NAME
+
+spamassassin - simple front-end filtering script for SpamAssassin
+
+=head1 SYNOPSIS
+
+B<spamassassin> [options] [ < I<mailmessage> | I<path> ... ]
+
+B<spamassassin> B<-d> [ < I<mailmessage> | I<path> ... ]
+
+B<spamassassin> B<-r> [B<-w> I<addr>] [ < I<mailmessage> | I<path> ... ]
+
+B<spamassassin> B<-k> [B<-w> I<addr>] [ < I<mailmessage> | I<path> ... ]
+
+B<spamassassin> B<-W>|B<-R> [ < I<mailmessage> | I<path> ... ]
+
+Options:
+
+ -L, --local Local tests only (no online tests)
+ -r, --report Report message as spam
+ -k, --revoke Revoke message as spam
+ -d, --remove-markup Remove spam reports from a message
+ -C path, --configpath=path, --config-file=path
+ Path to standard configuration dir
+ -p prefs, --prefspath=file, --prefs-file=file
+ Set user preferences file
+ --siteconfigpath=path Path for site configs
+ (def: /etc/mail/spamassassin)
+ -x, --nocreate-prefs Don't create user preferences file
+ -e, --exit-code Exit with a non-zero exit code if the
+ tested message was spam
+ --mbox read in messages in mbox format
+ --mbx read in messages in UW mbx format
+ -t, --test-mode Pipe message through and add extra
+ report to the bottom
+ --lint Lint the rule set: report syntax errors
+ -W, --add-to-whitelist Add addresses in mail to persistent address whitelist
+ --add-to-blacklist Add addresses in mail to persistent address blacklist
+ -R, --remove-from-whitelist Remove all addresses found in mail from
+ persistent address list
+ --add-addr-to-whitelist=addr Add addr to persistent address whitelist
+ --add-addr-to-blacklist=addr Add addr to persistent address blacklist
+ --remove-addr-from-whitelist=addr Remove addr from persistent address list
+ -D, --debug [area=n,...] Print debugging messages
+ -V, --version Print version
+ -h, --help Print usage message
+
+=head1 DESCRIPTION
+
+spamassassin is a simple front-end filter for SpamAssassin.
+
+Using the SpamAssassin rule base, it uses a wide range of heuristic
+tests on mail headers and body text to identify "spam", also known as
+unsolicited bulk email. Once identified, the mail is then tagged as
+spam for later filtering using the user's own mail user-agent
+application.
+
+The default tagging operations that take place are detailed in L</TAGGING>.
+
+By default, message(s) are read in from STDIN (< I<mailmessage>), or
+from specified files and directories (I<path> ...) STDIN and files
+are assumed to be in I<file> format, with a single message per file.
+Directories are assumed to be in a format where each file in the directory
+contains only one message (directories are not recursed and filenames
+containing whitespace or beginning with "." or "," are skipped).
+The options I<--mbox> and I<--mbx> can override the assumed format,
+see the appropriate OPTION information below.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-e>, B<--error-code>, B<--exit-code>
+
+Exit with a non-zero error code, if the message is determined to be
+spam.
+
+=item B<-h>, B<--help>
+
+Print help message and exit.
+
+=item B<-V>, B<--version>
+
+Print version and exit.
+
+=item B<-t>, B<--test-mode>
+
+Test mode. Pipe message through and add extra report. Note that the report
+text assumes that the message is spam, since in normal use it is only visible
+in this case. Pay attention to the score instead.
+
+If you run this with B<-d>, the message will first have SpamAssassin
+markup removed before being tested.
+
+=item B<-r>, B<--report>
+
+Report this message as manually-verified spam. This will submit the mail
+message read from STDIN to various spam-blocker databases. Currently,
+these are the Distributed Checksum Clearinghouse
+C<http://www.rhyolite.com/anti-spam/dcc/>, Pyzor
+C<http://pyzor.sourceforge.net/>, Vipul's Razor
+C<http://razor.sourceforge.net/>, and SpamCop C<http://www.spamcop.net/>.
+
+If the message contains SpamAssassin markup, the markup will be stripped
+out automatically before submission. The support modules for DCC, Pyzor,
+and Razor must be installed for spam to be reported to each service.
+SpamCop reports will have greater effect if you register and set the
+C<spamcop_to_address> option.
+
+The message will also be submitted to SpamAssassin's learning systems;
+currently this is the internal Bayesian statistical-filtering system (the
+BAYES rules). (Note that if you I<only> want to perform statistical
+learning, and do not want to report mail to third-parties, you should use
+the C<sa-learn> command directly instead.)
+
+=item B<-k>, B<--revoke>
+
+Revoke this message. This will revoke the mail message read from STDIN from
+various spam-blocker databases. Currently, these are Vipul's Razor.
+
+Revocation support for the Distributed Checksum Clearinghouse, Pyzor, and
+SpamCop is not currently available.
+
+If the message contains SpamAssassin markup, the markup will be stripped
+out automatically before submission. The support modules for Razor must
+be installed for spam to be revoked from the service.
+
+The message will also be submitted as 'ham' (non-spam) to SpamAssassin's
+learning systems; currently this is the internal Bayesian
+statistical-filtering system (the BAYES rules). (Note that if you I<only>
+want to perform statistical learning, and do not want to report mail to
+third-parties, you should use the C<sa-learn> command directly instead.)
+
+=item B<--lint>
+
+Syntax check (lint) the rule set and configuration files, reporting
+typos and rules that do not compile correctly. Exits with 0 if there
+are no errors, or greater than 0 if any errors are found.
+
+=item B<-W>, B<--add-to-whitelist>
+
+Add all email addresses, in the headers and body of the mail message read
+from STDIN, to a persistent address whitelist. Note that you must be running
+C<spamassassin> or C<spamd> with a persistent address list plugin enabled for
+this to work.
+
+=item B<--add-to-blacklist>
+
+Add all email addresses, in the headers and body of the mail message read
+from STDIN, to the persistent address blacklist. Note that you must be
+running C<spamassassin> or C<spamd> with a persistent address list plugin
+enabled for this to work.
+
+=item B<-R>, B<--remove-from-whitelist>
+
+Remove all email addresses, in the headers and body of the mail message read
+from STDIN, from a persistent address list. STDIN must contain a full email
+message, so to remove a single address you should use
+B<--remove-addr-from-whitelist> instead.
+
+Note that you must be running C<spamassassin> or C<spamd> with a persistent
+address list plugin enabled for this to work.
+
+=item B<--add-addr-to-whitelist>
+
+Add the named email address to a persistent address whitelist. Note that you
+must be running C<spamassassin> or C<spamd> with a persistent address list
+plugin enabled for this to work.
+
+=item B<--add-addr-to-blacklist>
+
+Add the named email address to a persistent address blacklist. Note that you
+must be running C<spamassassin> or C<spamd> with a persistent address list
+plugin enabled for this to work.
+
+=item B<--remove-addr-from-whitelist>
+
+Remove the named email address from a persistent address whitelist. Note that
+you must be running C<spamassassin> or C<spamd> with a persistent address
+list plugin enabled for this to work.
+
+=item B<-L>, B<--local>
+
+Do only the ''local'' tests, ones that do not require an internet connection to
+operate. Normally, SpamAssassin will try to detect whether you are connected
+to the net before doing these tests anyway, but for faster checks you may wish
+to use this.
+
+Note that SpamAssassin's network rules are run in parallel. This can cause
+overhead in terms of the number of file descriptors required if B<--local> is
+not used; it is recommended that the minimum limit on fds be raised to at least
+256 for safety.
+
+=item B<-d>, B<--remove-markup>
+
+Remove SpamAssassin markup (the "SpamAssassin results" report, X-Spam-Status
+headers, etc.) from the mail message. The resulting message, which will be
+more or less identical to the original, pre-SpamAssassin input, will be output
+to STDOUT.
+
+(Note: the message will not be exactly identical; some headers will be
+reformatted due to some features of the Mail::Internet package, but the body
+text will be.)
+
+=item B<-C> I<path>, B<--configpath>=I<path>, B<--config-file>=I<path>
+
+Use the specified path for locating the distributed configuration files.
+Ignore the default directories (usually C</usr/share/spamassassin> or similar).
+
+=item B<--siteconfigpath>=I<path>
+
+Use the specified path for locating site-specific configuration files. Ignore
+the default directories (usually C</etc/mail/spamassassin> or similar).
+
+=item B<-p> I<prefs>, B<--prefspath>=I<prefs>, B<--prefs-file>=I<prefs>
+
+Read user score preferences from I<prefs> (usually C<$HOME/.spamassassin/user_prefs>).
+
+=item B<-D> [I<area,...>], B<--debug> [I<area,...>]
+
+Produce debugging output. If no areas are listed, all debugging information is
+printed. Diagnostic output can also be enabled for each area individually;
+I<area> is the area of the code to instrument. For example, to produce
+diagnostic output on bayes, learn, and dns, use:
+
+ spamassassin -D bayes,learn,dns
+
+Higher priority informational messages that are suitable for logging in normal
+circumstances are available with an area of "info".
+
+=item B<-x>, B<--nocreate-prefs>
+
+Disable creation of user preferences file.
+
+=item B<--mbox>
+
+Specify that the input message(s) are in mbox format. mbox is a standard
+Unix message folder format.
+
+=item B<--mbx>
+
+Specify that the input message(s) are in UW .mbx format. mbx is
+the mailbox format used within the University of Washington's IMAP
+implementation; see C<http://www.washington.edu/imap/>.
+
+=back
+
+=head1 SEE ALSO
+
+sa-learn(1)
+spamd(1)
+spamc(1)
+Mail::SpamAssassin::Conf(3)
+Mail::SpamAssassin(3)
+
+=head1 PREREQUISITES
+
+C<Mail::SpamAssassin>
+
+=head1 BUGS
+
+See <http://bugzilla.spamassassin.org/>
+
+=head1 AUTHORS
+
+The SpamAssassin(tm) Project <http://spamassassin.apache.org/>
+
+=head1 COPYRIGHT
+
+SpamAssassin is distributed under the Apache License, Version 2.0, as
+described in the file C<LICENSE> included with the distribution.
+
+=cut
+
Copied: spamassassin/trunk/spamassassin.raw (from r157182, spamassassin/trunk/sa-filter.raw)
URL: http://svn.apache.org/viewcvs/spamassassin/trunk/spamassassin.raw?view=diff&rev=157194&p1=spamassassin/trunk/sa-filter.raw&r1=157182&p2=spamassassin/trunk/spamassassin.raw&r2=157194
==============================================================================
--- spamassassin/trunk/sa-filter.raw (original)
+++ spamassassin/trunk/spamassassin.raw Fri Mar 11 16:48:25 2005
@@ -49,7 +49,7 @@
# Firstly, are we running "make test" in the "t" dir? the test files
# *need* to use 'blib', so that 'use bytes' is removed for pre-5.6 perls
- # beforehand by the preproc. However, ./sa-filter does not, as the
+ # beforehand by the preproc. However, ./spamassassin does not, as the
# preproc will have stripped out the "use rule files from cwd" code from
# Mail::SpamAssassin. So we want to use blib just for the t scripts.
if ( $bin eq '../' && -e '../blib/lib/Mail/SpamAssassin.pm' ) {
@@ -188,21 +188,21 @@
# last in 2.3
'pipe|P' => sub { warn "The -P option is deprecated as 'pipe mode' is now the default behavior, ignoring.\n" },
- 'F:i' => sub { warn "The -F option has been removed from sa-filter, please remove from your commandline and re-run.\n"; exit 2; },
- 'add-from!' => sub { warn "The --add-from option has been removed from sa-filter, please remove from your commandline and re-run.\n"; exit 2; },
+ 'F:i' => sub { warn "The -F option has been removed from spamassassin, please remove from your commandline and re-run.\n"; exit 2; },
+ 'add-from!' => sub { warn "The --add-from option has been removed from spamassassin, please remove from your commandline and re-run.\n"; exit 2; },
# last in 2.4
'stop-at-threshold|S' => sub { warn "The -S option has been deprecated and is no longer supported, ignoring.\n" },
# last in 2.6
'log-to-mbox|l:s' => sub { warn "The -l option has been deprecated and is no longer supported, ignoring.\n" },
- 'warning-from|w:s' => sub { warn "The -w option has been removed from sa-filter, please remove from your commandline and re-run.\n"; exit 2; },
- 'whitelist-factory|M:s' => sub { warn "The -M option has been removed from sa-filter, please remove from your commandline and re-run.\n"; exit 2; },
+ 'warning-from|w:s' => sub { warn "The -w option has been removed from spamassassin, please remove from your commandline and re-run.\n"; exit 2; },
+ 'whitelist-factory|M:s' => sub { warn "The -M option has been removed from spamassassin, please remove from your commandline and re-run.\n"; exit 2; },
) or print_usage_and_exit();
if ( defined $opt{'help'} ) {
- print_usage_and_exit("For more information read the sa-filter man page.\n", 'EX_OK');
+ print_usage_and_exit("For more information read the spamassassin man page.\n", 'EX_OK');
}
if ( defined $opt{'version'} ) {
print_version();
@@ -438,264 +438,297 @@
# ---------------------------------------------------------------------------
+=cut
+
=head1 NAME
-sa-filter - mail filter to identify spam using SpamAssassin
+spamassassin - extensible email filter used to identify spam
=head1 SYNOPSIS
-B<sa-filter> [options] [ < I<mailmessage> | I<path> ... ]
+For backwards compatibility, running "spamassassin" calls the "spamassassin"
+program. You should be able to view the "spamassassin" documentation with
+your man(1) program or perldoc(1).
-B<sa-filter> B<-d> [ < I<mailmessage> | I<path> ... ]
+=head1 DESCRIPTION
-B<sa-filter> B<-r> [B<-w> I<addr>] [ < I<mailmessage> | I<path> ... ]
+SpamAssassin is an intelligent email filter which uses a diverse range of
+tests to identify unsolicited bulk email, more commonly known as "spam".
+These tests are applied to email headers and content to classify email
+using advanced statistical methods. In addition, SpamAssassin has a
+modular architecture that allows other technologies to be quickly wielded
+against spam and is designed for easy integration into virtually any email
+system.
-B<sa-filter> B<-k> [B<-w> I<addr>] [ < I<mailmessage> | I<path> ... ]
+=head1 SYNOPSIS
-B<sa-filter> B<-W>|B<-R> [ < I<mailmessage> | I<path> ... ]
-
-Options:
-
- -L, --local Local tests only (no online tests)
- -r, --report Report message as spam
- -k, --revoke Revoke message as spam
- -d, --remove-markup Remove spam reports from a message
- -C path, --configpath=path, --config-file=path
- Path to standard configuration dir
- -p prefs, --prefspath=file, --prefs-file=file
- Set user preferences file
- --siteconfigpath=path Path for site configs
- (def: /etc/mail/spamassassin)
- -x, --nocreate-prefs Don't create user preferences file
- -e, --exit-code Exit with a non-zero exit code if the
- tested message was spam
- --mbox read in messages in mbox format
- --mbx read in messages in UW mbx format
- -t, --test-mode Pipe message through and add extra
- report to the bottom
- --lint Lint the rule set: report syntax errors
- -W, --add-to-whitelist Add addresses in mail to persistent address whitelist
- --add-to-blacklist Add addresses in mail to persistent address blacklist
- -R, --remove-from-whitelist Remove all addresses found in mail from
- persistent address list
- --add-addr-to-whitelist=addr Add addr to persistent address whitelist
- --add-addr-to-blacklist=addr Add addr to persistent address blacklist
- --remove-addr-from-whitelist=addr Remove addr from persistent address list
- -D, --debug [area=n,...] Print debugging messages
- -V, --version Print version
- -h, --help Print usage message
+For ease of access, the SpamAssassin manual has been split up into several
+sections:
-=head1 DESCRIPTION
+ spamassassin SpamAssassin overview (this section)
+ Mail::SpamAssassin::Conf SpamAssassin configuration files
+ spamassassin-script "spamassassin" front-end filtering script
+ sa-learn train SpamAssassin's Bayesian classifier
+ spamc client for "spamd" (faster than "spamassassin")
+ spamd spamassassin server (faster than "spamassassin")
+
+(If you're intending to read these straight through for the first time,
+the suggested order will tend to reduce the number of forward references.)
+
+Extensive additional documentation for SpamAssassin is available,
+primarily on the SpamAssassin web site and wiki.
-sa-filter is a simple front-end filter for SpamAssassin.
+You should be able to view SpamAssassin's documentation with your man(1)
+program or perldoc(1).
-Using the SpamAssassin rule base, it uses a wide range of heuristic
-tests on mail headers and body text to identify "spam", also known as
-unsolicited bulk email. Once identified, the mail is then tagged as
-spam for later filtering using the user's own mail user-agent
-application.
-
-The default tagging operations that take place are detailed in L</TAGGING>.
-
-By default, message(s) are read in from STDIN (< I<mailmessage>), or
-from specified files and directories (I<path> ...) STDIN and files
-are assumed to be in I<file> format, with a single message per file.
-Directories are assumed to be in a format where each file in the directory
-contains only one message (directories are not recursed and filenames
-containing whitespace or beginning with "." or "," are skipped).
-The options I<--mbox> and I<--mbx> can override the assumed format,
-see the appropriate OPTION information below.
+=head1 WEB SITES
-=head1 OPTIONS
+ SpamAssassin web site: http://spamassassin.apache.org/
+ Wiki-based documentation: http://wiki.apache.org/spamassassin/
+
+=head1 USER MAILING LIST
+
+A users mailing list exists where other experienced users are often able
+to help and provide tips and advice. Subscription instructions are
+located on the SpamAssassin web site.
+
+=head1 CONFIGURATION FILES
+
+The SpamAssassin rule base, text templates, and rule description text
+are loaded from configuration files.
+
+Default configuration data is loaded from the first existing directory
+in:
=over 4
-=item B<-e>, B<--error-code>, B<--exit-code>
+=item @@DEF_RULES_DIR@@
-Exit with a non-zero error code, if the message is determined to be
-spam.
+=item @@PREFIX@@/share/spamassassin
-=item B<-h>, B<--help>
+=item /usr/local/share/spamassassin
-Print help message and exit.
+=item /usr/share/spamassassin
-=item B<-V>, B<--version>
+=back
-Print version and exit.
+Site-specific configuration data is used to override any values which had
+already been set. This is loaded from the first existing directory in:
-=item B<-t>, B<--test-mode>
+=over 4
-Test mode. Pipe message through and add extra report. Note that the report
-text assumes that the message is spam, since in normal use it is only visible
-in this case. Pay attention to the score instead.
+=item @@LOCAL_RULES_DIR@@
-If you run this with B<-d>, the message will first have SpamAssassin
-markup removed before being tested.
+=item @@PREFIX@@/etc/mail/spamassassin
-=item B<-r>, B<--report>
+=item @@PREFIX@@/etc/spamassassin
-Report this message as manually-verified spam. This will submit the mail
-message read from STDIN to various spam-blocker databases. Currently,
-these are the Distributed Checksum Clearinghouse
-C<http://www.rhyolite.com/anti-spam/dcc/>, Pyzor
-C<http://pyzor.sourceforge.net/>, Vipul's Razor
-C<http://razor.sourceforge.net/>, and SpamCop C<http://www.spamcop.net/>.
+=item /usr/local/etc/spamassassin
-If the message contains SpamAssassin markup, the markup will be stripped
-out automatically before submission. The support modules for DCC, Pyzor,
-and Razor must be installed for spam to be reported to each service.
-SpamCop reports will have greater effect if you register and set the
-C<spamcop_to_address> option.
+=item /usr/pkg/etc/spamassassin
-The message will also be submitted to SpamAssassin's learning systems;
-currently this is the internal Bayesian statistical-filtering system (the
-BAYES rules). (Note that if you I<only> want to perform statistical
-learning, and do not want to report mail to third-parties, you should use
-the C<sa-learn> command directly instead.)
+=item /usr/etc/spamassassin
-=item B<-k>, B<--revoke>
+=item /etc/mail/spamassassin
-Revoke this message. This will revoke the mail message read from STDIN from
-various spam-blocker databases. Currently, these are Vipul's Razor.
+=item /etc/spamassassin
-Revocation support for the Distributed Checksum Clearinghouse, Pyzor, and
-SpamCop is not currently available.
+=back
-If the message contains SpamAssassin markup, the markup will be stripped
-out automatically before submission. The support modules for Razor must
-be installed for spam to be revoked from the service.
+From those two directories, SpamAssassin will first read files ending in
+".pre" in lexical order and then it will read files ending in ".cf" in
+lexical order (most files begin with two numbers to make the sorting
+order obvious).
+
+In other words, it will read F<init.pre> first, then F<10_misc.cf> before
+F<50_scores.cf> and F<20_body_tests.cf> before F<20_head_tests.cf>.
+Options in later files will override earlier files.
+
+Individual user preferences are loaded from the location specified on
+the C<spamassassin>, C<sa-learn>, or C<spamd> command line (see respective
+manual page for details). If the location is not specified,
+F<~/.spamassassin/user_prefs> is used if it exists. SpamAssassin will
+create that file if it does not already exist, using
+F<user_prefs.template> as a template. That file will be looked for in:
-The message will also be submitted as 'ham' (non-spam) to SpamAssassin's
-learning systems; currently this is the internal Bayesian
-statistical-filtering system (the BAYES rules). (Note that if you I<only>
-want to perform statistical learning, and do not want to report mail to
-third-parties, you should use the C<sa-learn> command directly instead.)
+=over 4
-=item B<--lint>
+=item @@LOCAL_RULES_DIR@@
-Syntax check (lint) the rule set and configuration files, reporting
-typos and rules that do not compile correctly. Exits with 0 if there
-are no errors, or greater than 0 if any errors are found.
+=item @@PREFIX@@/etc/mail/spamassassin
-=item B<-W>, B<--add-to-whitelist>
+=item @@PREFIX@@/share/spamassassin
-Add all email addresses, in the headers and body of the mail message read
-from STDIN, to a persistent address whitelist. Note that you must be running
-C<sa-filter> or C<spamd> with a persistent address list plugin enabled for
-this to work.
+=item /etc/spamassassin
-=item B<--add-to-blacklist>
+=item /etc/mail/spamassassin
-Add all email addresses, in the headers and body of the mail message read
-from STDIN, to the persistent address blacklist. Note that you must be
-running C<sa-filter> or C<spamd> with a persistent address list plugin
-enabled for this to work.
+=item /usr/local/share/spamassassin
-=item B<-R>, B<--remove-from-whitelist>
+=item /usr/share/spamassassin
-Remove all email addresses, in the headers and body of the mail message read
-from STDIN, from a persistent address list. STDIN must contain a full email
-message, so to remove a single address you should use
-B<--remove-addr-from-whitelist> instead.
+=back
-Note that you must be running C<sa-filter> or C<spamd> with a persistent
-address list plugin enabled for this to work.
+=head1 TAGGING
-=item B<--add-addr-to-whitelist>
+The following two sections detail the default tagging and markup that
+takes place for messages when running C<spamassassin> or C<spamc> with
+C<spamd> in the default configuration.
-Add the named email address to a persistent address whitelist. Note that you
-must be running C<sa-filter> or C<spamd> with a persistent address list
-plugin enabled for this to work.
+=head2 TAGGING FOR SPAM MAILS
-=item B<--add-addr-to-blacklist>
+By default, all messages with a calculated score of 5.0 or higher are
+tagged as spam.
-Add the named email address to a persistent address blacklist. Note that you
-must be running C<sa-filter> or C<spamd> with a persistent address list
-plugin enabled for this to work.
+If an incoming message is tagged as spam, instead of modifying the
+original message, SpamAssassin will create a new report message and
+attach the original message as a message/rfc822 MIME part (ensuring the
+original message is completely preserved and easier to recover).
-=item B<--remove-addr-from-whitelist>
+The new report message inherits the following headers (if they are
+present) from the original spam message:
-Remove the named email address from a persistent address whitelist. Note that
-you must be running C<sa-filter> or C<spamd> with a persistent address
-list plugin enabled for this to work.
+=over 4
-=item B<-L>, B<--local>
+=item From: header
-Do only the ''local'' tests, ones that do not require an internet connection to
-operate. Normally, SpamAssassin will try to detect whether you are connected
-to the net before doing these tests anyway, but for faster checks you may wish
-to use this.
+=item To: header
-Note that SpamAssassin's network rules are run in parallel. This can cause
-overhead in terms of the number of file descriptors required if B<--local> is
-not used; it is recommended that the minimum limit on fds be raised to at least
-256 for safety.
+=item Cc: header
-=item B<-d>, B<--remove-markup>
+=item Subject: header
-Remove SpamAssassin markup (the "SpamAssassin results" report, X-Spam-Status
-headers, etc.) from the mail message. The resulting message, which will be
-more or less identical to the original, pre-SpamAssassin input, will be output
-to STDOUT.
+=item Date: header
-(Note: the message will not be exactly identical; some headers will be
-reformatted due to some features of the Mail::Internet package, but the body
-text will be.)
+=item Message-ID: header
-=item B<-C> I<path>, B<--configpath>=I<path>, B<--config-file>=I<path>
+=back
-Use the specified path for locating the distributed configuration files.
-Ignore the default directories (usually C</usr/share/spamassassin> or similar).
+The above headers can be modified if the relevant C<rewrite_header>
+option is given (see C<Mail::SpamAssassin::Conf> for more information).
-=item B<--siteconfigpath>=I<path>
+By default these message headers are added to spam:
-Use the specified path for locating site-specific configuration files. Ignore
-the default directories (usually C</etc/mail/spamassassin> or similar).
+=over 4
-=item B<-p> I<prefs>, B<--prefspath>=I<prefs>, B<--prefs-file>=I<prefs>
+=item X-Spam-Flag: header
-Read user score preferences from I<prefs> (usually C<$HOME/.spamassassin/user_prefs>).
+Set to C<YES>.
-=item B<-D> [I<area,...>], B<--debug> [I<area,...>]
+=back
-Produce debugging output. If no areas are listed, all debugging information is
-printed. Diagnostic output can also be enabled for each area individually;
-I<area> is the area of the code to instrument. For example, to produce
-diagnostic output on bayes, learn, and dns, use:
+The headers that added are fully configurable via the C<add_header>
+option (see C<Mail::SpamAssassin::Conf> for more information).
- sa-filter -D bayes,learn,dns
+=over 4
+
+=item spam mail body text
+
+The SpamAssassin report is added to top of the mail message body,
+if the message is marked as spam.
-Higher priority informational messages that are suitable for logging in normal
-circumstances are available with an area of "info".
+=back
+
+=head2 DEFAULT TAGGING FOR ALL MAILS
-=item B<-x>, B<--nocreate-prefs>
+These headers are added to all messages, both spam and ham (non-spam).
-Disable creation of user preferences file.
+=over 4
-=item B<--mbox>
+=item X-Spam-Checker-Version: header
-Specify that the input message(s) are in mbox format. mbox is a standard
-Unix message folder format.
+The version and subversion of SpamAssassin and the host where
+SpamAssassin was run.
-=item B<--mbx>
+=item X-Spam-Level: header
-Specify that the input message(s) are in UW .mbx format. mbx is
-the mailbox format used within the University of Washington's IMAP
-implementation; see C<http://www.washington.edu/imap/>.
+A series of "*" charactes where each one represents a full score point.
+
+=item X-Spam-Status: header
+
+A string, C<(Yes|No), score=nn required=nn tests=xxx,xxx
+autolearn=(ham|spam|no|unavailable|failed)> is set in this header to
+reflect the filter status. For the first word, "Yes" means spam and
+"No" means ham (non-spam).
=back
-=head1 SEE ALSO
+The headers that added are fully configurable via the C<add_header>
+option (see C<Mail::SpamAssassin::Conf> for more information).
+
+=head1 INSTALLATION
+
+The B<spamassassin> command is part of the B<Mail::SpamAssassin> Perl module.
+Install this as a normal Perl module, using C<perl -MCPAN -e shell>, or by
+hand.
+
+For further details on how to install, please read the C<INSTALL> file
+from the SpamAssassin distribution.
+
+=head1 DEVELOPER DOCUMENTATION
+
+ Mail::SpamAssassin
+ Spam detector and markup engine
+
+ Mail::SpamAssassin::ArchiveIterator
+ find and process messages one at a time
+
+ Mail::SpamAssassin::AutoWhitelist
+ auto-whitelist handler for SpamAssassin
+
+ Mail::SpamAssassin::Bayes
+ determine spammishness using a Bayesian classifier
+
+ Mail::SpamAssassin::BayesStore
+ Bayesian Storage Module
+
+ Mail::SpamAssassin::BayesStore::SQL
+ SQL Bayesian Storage Module Implementation
+
+ Mail::SpamAssassin::Conf::LDAP
+ load SpamAssassin scores from LDAP database
-sa-learn(1)
-spamd(1)
-spamc(1)
-Mail::SpamAssassin::Conf(3)
-Mail::SpamAssassin(3)
+ Mail::SpamAssassin::Conf::Parser
+ parse SpamAssassin configuration
-=head1 PREREQUISITES
+ Mail::SpamAssassin::Conf::SQL
+ load SpamAssassin scores from SQL database
-C<Mail::SpamAssassin>
+ Mail::SpamAssassin::Message
+ decode, render, and hold an RFC-2822 message
+
+ Mail::SpamAssassin::Message::Metadata
+ extract metadata from a message
+
+ Mail::SpamAssassin::Message::Node
+ decode, render, and make available MIME message parts
+
+ Mail::SpamAssassin::PerMsgLearner
+ per-message status (spam or not-spam)
+
+ Mail::SpamAssassin::PerMsgStatus
+ per-message status (spam or not-spam)
+
+ Mail::SpamAssassin::PersistentAddrList
+ persistent address list base class
+
+ Mail::SpamAssassin::Plugin
+ SpamAssassin plugin base class
+
+ Mail::SpamAssassin::Plugin::Hashcash
+ perform hashcash verification tests
+
+ Mail::SpamAssassin::Plugin::RelayCountry
+ add message metadata indicating the country code of each relay
+
+ Mail::SpamAssassin::Plugin::SPF
+ perform SPF verification tests
+
+ Mail::SpamAssassin::Plugin::URIDNSBL
+ look up URLs against DNS blocklists
+
+ Mail::SpamAssassin::SQLBasedAddrList
+ SpamAssassin SQL Based Auto Whitelist
=head1 BUGS
@@ -709,6 +742,4 @@
SpamAssassin is distributed under the Apache License, Version 2.0, as
described in the file C<LICENSE> included with the distribution.
-
-=cut