NAME

       bmf - efficient Bayesian mail filter

SYNOPSIS

       bmf [-t] [-n] [-s] [-N] [-S] [-f fmt] [-d db] [-i file] [-k n] [-m type] [-p]
           [-v] [-V] [-h]

DESCRIPTION

       bmf  is a Bayesian mail filter. In its normal mode of operation, it takes an email message
       or other text on standard input, does a statistical check  against  lists  of  "good"  and
       "spam"  words, registers the new data, and returns a status code indicating whether or not
       the message is spam. BMF is written with fast, zero-copy algorithms, coded directly in  C,
       and  tuned  for  speed.  It  aims  to  be faster, smaller, and more versatile than similar
       applications.

       bmf supports both mbox and maildir mail storage formats.  It  will  automatically  process
       multiple messages within an mbox file separately.

OPTIONS

       Without  command-line  options,  bmf processes the input, registers it as either "good" or
       "spam", and returns the appropriate error code. The  wordlist  directory  and  nonexistent
       wordfiles are created if absent.

       -t  Test  to see if the input is spam. The word lists are not updated. A report is written
       to stdout showing the final score and the tokens with the highest deviation form a mean of
       0.5.

       -n Register the input as non-spam.

       -s Register the input as spam.

       -N Register the input as non-spam and undo a prior registration as spam.

       -S Register the input as spam and undo a prior registration as non-spam.

       -f  fmt  Specify  database  format.  Valid formats are text, db, and mysql. Text is always
       valid. The others may not be available if the corresponding  option  was  not  enabled  at
       compile time. The default is db if available, else text.

       -d  db  Specify  database  or  directory for loading and saving word lists. The default is
       ~/.bmf in text mode.

       -i file Use file for input instead of stdin.

       -k n Specify the number of extrema (keepers) to use in the Bayes calculation. The  default
       is 15.

       -m  fmt Specify mail storage format. Valid formats are mbox and maildir. The default is to
       automatically detect the mail storage format. This option is deprecated.

       -p Copy the input to the output (passthrough) and insert spam  headers  in  the  style  of
       SpamAssassin.  An  X-Spam-Status  header  is  always inserted with processing details. The
       contents of this header always begin with either "Yes" or "No". If the input is judged  to
       be spam, the header "X-Spam-Flag: YES" is also inserted.

       -v Be more verbose. This option is not well supported yet.

       -V Display version information.

       -h Display usage information.

THEORY OF OPERATION

       bmf  treats  its  input as a bag of tokens. Each token is checked against "good" and "bad"
       wordlists, which maintain counts of the numbers of times it has occurred in  non-spam  and
       spam  mails.  These  numbers  are used to compute the probability that a mail in which the
       token occurs is spam. After probabilities for all input tokens have been computed, a fixed
       number  of the probabilities that deviate furthest from average are combined using Bayes's
       theorem on conditional probabilities.

       While this method sounds crude compared to the more usual  pattern-matching  approach,  it
       turns   out   to   be   extremely   effective.  Paul  Graham's  paper  A  Plan  For  Spam:
       http://www.paulgraham.com/spam.html is recommended reading.

       bmf improves on  Paul's  proposal  by  doing  smarter  lexical  analysis.  In  particular,
       hostnames  and  IP  addresses  are not discarded, and certain types of MTA information are
       discarded (such as message ids and dates).

       MIME and other attachments are not decoded. Experience from  watching  the  token  streams
       suggests  that  spam  with  enclosures  invariably  gives  itself away through cues in the
       headers and non-enclosure parts. Nonetheless, I would like to add the  ability  to  decode
       quoted-printable and perhaps base64 encodings for textual attachments.

INTEGRATION WITH OTHER TOOLS

       Please see the /usr/share/doc/bmf/README.gz for samples and suggestions.

RETURN VALUES

       In passthrough mode: zero for success, nonzero for failure.

       In non-passthrough mode: 0 for spam; 1 for non-spam; 2 for I/O or other errors.

FILES

       ~/.bmf/goodlist.txt
              List of good tokens for text mode.

       ~/.bmf/spamlist.txt
              List of bad tokens for text mode.

       ~/.bmf/goodlist.db
              List of good tokens for libdb mode.

       ~/.bmf/spamlist.db
              List of bad tokens for libdb mode.

BUGS

       Only  one  copy  of  bmf(1)  instance  can access the database (see options -d and -f). In
       Procmail recipes, ensure sequential access with a lock file:

               :0 fw: bmf.lock
               | bmf -p

       The lexer does not recognize multiline headers.

       The lexer does not recognize MIME attachments.

       Content-Transfer-Encoding is not decoded.

AUTHOR

       Tom Marshall <tommy@tig-grr.com>.

       The Bayes algorithm is from bogofilter by Eric S.  Raymond  <esr@thyrsus.com>.  bogofilter
       can be found at the bogofilter project page: http://bogofilter.sourceforge.net/.

                                                                                           BMF(1)