bogofilter.1in

一个C语言写的快速贝叶斯垃圾邮件过滤工具

where to write its output in passthrough mode. Note that this only works when \-p is explicitly given.
.PP
PARAMETER OPTIONS
.PP
The
\fB\-E \fR\fB\fIvalue\fR\fI[,value]\fR\fR
option allows setting the sp\-esf value and the ns\-esf value. With two values, both sp\-esf and ns\-esf are set. If only one value is given, parameters are set as described in the note below.
.PP
The
\fB\-m \fR\fB\fIvalue\fR\fI[,value]\fR\fI[,value]\fR\fR
option allows setting the min\-dev value and, optionally, the robs and robx values. With three values, min\-dev, robs, and robx are all set. If fewer values are given, parameters are set as described in the note below.
.PP
The
\fB\-o \fR\fB\fIvalue\fR\fI[,value]\fR\fR
option allows setting the spam\-cutoff ham\-cutoff values. With two values, both spam\-cutoff and ham\-cutoff are set. If only one value is given, parameters are set as described in the note below.
.PP
Note: All of these options allow fewer values to be provided. Values can be skipped by using just the comma delimiter, in which case the corresponding parameter(s) won't be changed. If only the first value is provided, then only the first parameter is set. Trailing values can be skipped, in which case the corresponding parameters won't be changed. Within the parameter list, spaces are not allowed after commas.
.PP
INFO OPTIONS
.PP
The
\fB\-v\fR
option produces a report to standard output on
bogofilter's analysis of the input. Each additional
\fBv\fR
will increase the verbosity of the output, up to a maximum of 4. With
\fB\-vv\fR, the report lists the tokens with highest deviation from a mean of 0.5 association with spam.
.PP
Option
\fB\-y date\fR
can be used to override the current date when timestamping tokens. A value of zero (0) turns off timestamping.
.PP
The
\fB\-D\fR
option redirects debug output to stdout.
.PP
The
\fB\-x \fR\fB\fIflags\fR\fR
option allows setting of debug flags for printing debug information. See header file debug.h for the list of usable flags.
.PP
CONFIG FILE OPTIONS
.PP
Using GNU longopt
\fB\-\-\fR
syntax, a config file's
\fB\fIname=value\fR\fR
statement becomes a command line's
\fB\-\-\fR\fB\fIoption=value\fR\fR. Use command
\fBbogofilter \-\-help\fR
for a list of options and see
\fIbogofilter.cf.example\fR
for more info on them. For example to change the X\-Bogosity header to "X\-Spam\-Header", use:
.PP
\fB\fI\-\-spam\-header\-name=X\-Spam\-Header\fR\fR
.SH "ENVIRONMENT"
.PP
Bogofilter
uses a database directory, which can be set in the config file. If not set there,
bogofilter
will use the value of
\fBBOGOFILTER_DIR\fR. Both can be overridden by the
\fB\-d \fR\fB\fIdir\fR\fR
option. If none of that is available,
bogofilter
will use directory
\fI$HOME/.bogofilter\fR.
.SH "CONFIGURATION"
.PP
The
bogofilter
command line allows setting of many options that determine how
bogofilter
operates. File
\fI@sysconfdir@/bogofilter.cf\fR
can be used to set additional parameters that affect its operation. File
\fI@sysconfdir@/bogofilter.cf.example\fR
has samples of all of the parameters. Status and logging messages can be customized for each site.
.SH "RETURN VALUES"
.PP
0 for spam; 1 for non\-spam; 2 for unsure ; 3 for I/O or other errors.
.PP
If both
\fB\-p\fR
and
\fB\-e\fR
are used, the return values are: 0 for spam or non\-spam; 3 for I/O or other errors.
.PP
Error 3 usually means that the wordlist file
bogofilter
wants to read at startup is missing or the hard disk has filled up in
\fB\-p\fR
mode.
.SH "INTEGRATION WITH OTHER TOOLS"
.PP
Use with procmail
.PP
The following recipe (a) spam\-bins anything that
bogofilter
rates as spam, (b) registers the words in messages rated as spam as such, and (c) registers the words in messages rated as non\-spam as such. With this in place, it will normally only be necessary for the user to intervene (with
\fB\-Ns\fR
or
\fB\-Sn\fR) when
bogofilter
miscategorizes something.
.sp
.nf

# filter mail through bogofilter, tagging it as Ham, Spam, or Unsure,
# and updating the wordlist

:0fw
| bogofilter \-u \-e \-p


# if bogofilter failed, return the mail to the queue;
# the MTA will retry to deliver it later
# 75 is the value for EX_TEMPFAIL in /usr/include/sysexits.h

:0e
{ EXITCODE=75 HOST }


# file the mail to \fIspam\-bogofilter\fR if it's spam.

:0:
* ^X\-Bogosity: Spam, tests=bogofilter
spam\-bogofilter

# file the mail to \fIunsure\-bogofilter\fR 
# if it's neither ham nor spam.

:0:
* ^X\-Bogosity: Unsure, tests=bogofilter
unsure\-bogofilter

# With this recipe, you can train bogofilter starting with an empty
# wordlist.  Be sure to check your unsure\-folder regularly, take the
# messages out of it, classify them as ham (or spam), and use them to
# train bogofilter.

.fi
.PP
The following procmail rule will take mail on stdin and save it to file
\fIspam\fR
if
bogofilter
thinks it's spam:
.sp
.nf
:0HB:
* ? bogofilter
spam
.fi
.sp
and this similar rule will also register the tokens in the mail according to the
bogofilter
classification:
.sp
.nf
:0HB:
* ? bogofilter \-u
spam
.fi
.sp
.PP
If
bogofilter
fails (returning 3) the message will be treated as non\-spam.
.PP
This one is for
maildrop, it automatically defers the mail and retries later when the
xfilter
command fails, use this in your
\fI~/.mailfilter\fR:
.sp
.nf
xfilter "bogofilter \-u \-e \-p"
if (/^X\-Bogosity: Spam, tests=bogofilter/)
{
  to "spam\-bogofilter"
}
.fi
.PP
The following
\fI.muttrc\fR
lines will create mutt macros for dispatching mail to
bogofilter.
.sp
.nf
macro index d "<enter\-command>unset wait_key\\n\\
<pipe\-entry>bogofilter \-n\\n\\
<enter\-command>set wait_key\\n\\
<delete\-message>" "delete message as non\-spam"
macro index \\ed "<enter\-command>unset wait_key\\n\\
<pipe\-entry>bogofilter \-s\\n\\
<enter\-command>set wait_key\\n\\
<delete\-message>" "delete message as spam"
.fi
.PP
Integration with Mail Transport Agent (MTA)
.TP 3
1.
bogofilter
can also be integrated into an MTA to filter all incoming mail. While the specific implementation is MTA dependent, the general steps are as follows:
.TP
2.
Install
bogofilter
on the mail server
.TP
3.
Prime the
bogofilter
databases with a spam and non\-spam corpus. Since
bogofilter
will be serving a larger community, it is important to prime it with a representative set of messages.
.TP
4.
Set up the MTA to invoke
bogofilter
on each message. While this is an MTA specific step, you'll probably need to use the
\fB\-p\fR,
\fB\-u\fR, and
\fB\-e\fR
options.
.TP
5.
Set up a mechanism for users to register spam/non\-spam messages, as well as to correct mis\-classifications. The most generic solution is to set up alias email addresses to which users bounce messages.
.TP
6.
See the
\fIdoc\fR
and
\fIcontrib\fR
directories for more information.
.PP
Use of R to verify
bogofilter's calculations
.PP
The \-R option tells
bogofilter
to generate an R data frame. The data frame contains one row per token analyzed. Each such row contains the token, the sum of its database "good" and "spam" counts, the "good" count divided by the number of non\-spam messages used to create the training database, the "spam" count divided by the spam message count, Robinson's f(w) for the token, the natural logs of (1 \- f(w)) and f(w), and an indicator character (+ if the token's f(w) value exceeded the minimum deviation from 0.5, \- if it didn't). There is one additional row at the end of the table that contains a label in the token field, followed by the number of words actually used (the ones with + indicators), Robinson's P, Q, S, s and x values and the minimum deviation.
.PP
The R data frame can be saved to a file and later read into an R session (see
[5]\&\fIthe R project website\fR
for information about the mathematics package R). Provided with the
bogofilter
distribution is a simple R script (file bogo.R) that can be used to verify
bogofilter's calculations. Instructions for its use are included in the script in the form of comments.
.SH "LOG MESSAGES"
.PP
Bogofilter
writes messages to the system log when the
\fB\-l\fR
option is used. What is written depends on which other flags are used.
.PP
A classification run will generate (we are not showing the date and host part here):
.sp
.nf
bogofilter[1412]: X\-Bogosity: Ham, spamicity=0.000227
bogofilter[1415]: X\-Bogosity: Spam, spamicity=0.998918
.fi
.PP
Using
\fB\-u\fR
to classify a message and update a wordlist will produce (one a single line):
.sp
.nf
bogofilter[1426]: X\-Bogosity: Spam, spamicity=0.998918,
  register \-s, 329 words, 1 messages
    
.fi
.PP
Registering words (\fB\-l\fR
and
\fB\-s\fR,
\fB\-n\fR,
\fB\-S\fR, or
\fB\-N\fR) will produce:
.sp
.nf
bogofilter[1440]: register\-n, 255 words, 1 messages
.fi
.PP
A registration run (using
\fB\-s\fR,
\fB\-n\fR,
\fB\-N\fR, or
\fB\-S\fR) will generate messages like:
.sp
.nf
bogofilter[17330]: register\-n, 574 words, 3 messages
bogofilter[6244]: register\-s, 1273 words, 4 messages
.fi
.SH "FILES"
.TP
\fI@sysconfdir@/bogofilter.cf\fR
System configuration file.
.TP
\fI~/.bogofilter.cf\fR
User configuration file.
.TP
\fI~/.bogofilter/wordlist.db\fR
Combined list of good and spam tokens.
.SH "AUTHOR"
.sp
.nf
Eric S. Raymond <[e-mail]>.
David Relson <[e-mail]>.
Matthias Andree <[e-mail]>.
Greg Louis <[e-mail]>.
.fi
.PP
For updates, see the
[6]\&\fI bogofilter project page\fR.
.SH "SEE ALSO "
.PP
bogolexer(1), bogotune(1), bogoupgrade(1), bogoutil(1)
.SH "REFERENCES"
.TP 3
1.\ A Plan For Spam
\%http://www.paulgraham.com/spam.html
.TP 3
2.\ Spam Detection
\%http://radio.weblogs.com/0101454/stories/2002/09/16/spamDetection.html
.TP 3
3.\ A Statistical Approach to the Spam Problem
\%http://www.linuxjournal.com/article/6467
.TP 3
4.\ Another improvement
\%http://www.garyrobinson.net/2004/04/improved_chi.html
.TP 3
5.\ the R project website
\%http://cran.r\-project.org/
.TP 3
6.\ bogofilter project page
\%http://bogofilter.sourceforge.net/