Provided by: qsf_1.2.7-1build2_amd64 bug

NAME

       qsf - quick spam filter

SYNOPSIS

       Filtering:       qsf [-snrAtav] [-d DB] [-g DB]
                            [-L LVL] [-S SUBJ] [-H MARK] [-Q NUM]
                            [-X NUM]
       Training:        qsf -T SPAM NONSPAM [MAXROUNDS] [-d DB]
       Retraining:      qsf -[m|M] [-d DB] [-w WEIGHT] [-ayN]
       Database:        qsf -[p|D|R|O] [-d DB]
       Database merge:  qsf -E OTHERDB [-d DB]
       Allowlist query: qsf -e EMAIL [-m|-M|-t] [-d DB] [-g DB]
       Denylist query:  qsf -y -e EMAIL [-m -m|-M -M|-t] [-d DB] [-g DB]
       Help:            qsf -[h|V]

DESCRIPTION

       qsf  reads a single email on standard input, and by default outputs it on standard output.
       If the email is determined to be spam, an additional header ("X-Spam: YES") will be added,
       and optionally the subject line can have "[SPAM]" prepended to it.

       qsf is intended to be used in a procmail(1) recipe, in a ruleset such as this:

               :0 wf
               | qsf -ra

               :0 H:
               * X-Spam: YES
               $HOME/mail/spam

       For more examples, including sample procmail(1) recipes, see the EXAMPLES section below.

TRAINING

       Before  qsf  can  be used properly, it needs to be trained.  A good way to train qsf is to
       collect a copy of all your email into two folders - one for spam, and  one  for  non-spam.
       Once you have done this, you can use the training function, like this:

               qsf -aT spam-folder non-spam-folder

       This  will  generate a database that can be used by qsf to guess whether email received in
       the future is spam or not.  Note that this initial training run may take a long time,  but
       you should only need to do it once.

       To  mark  a  single  message  as spam, pipe it to qsf with the --mark-spam or -m ("mark as
       spam") option.  This will update the database accordingly and discard the email.

       To mark a single message as non-spam, pipe it to qsf with the --mark-nonspam or -M  ("mark
       as non-spam") option.  Again, this will discard the email.

       If  a  message has been mis-tagged, simply send it to qsf as the opposite type, i.e. if it
       has been mistakenly tagged as spam, pipe it into qsf --mark-nonspam --weight=2 to  add  it
       to the non-spam side of the database with double the usual weighting.

OPTIONS

       The qsf options are listed below.

       -d, --database [TYPE:]FILE
              Use  FILE as the spam/non-spam database.  The default is to use /var/lib/qsfdb and,
              if that is not available or is read-only, $HOME/.qsfdb.  This option  can  also  be
              useful  if  there  is  a  system-wide  database  but  you  do  not want to use it -
              specifying your own here will override the default.

              If you prefix the filename with a TYPE, of the form btree:$HOME/.qsfdb,  then  this
              will  specify  what kind of database FILE is, such as list, btree, gdbm, sqlite and
              so on.  Check the output of qsf -V to see which database  backends  are  available.
              The default is to auto-detect the type, or, if the file does not already exist, use
              list.  Note that TYPE is not case-sensitive.

       -g, --global [TYPE:]FILE
              Use FILE as the default global database, instead of /var/lib/qsfdb.   If  you  also
              specify  a  database with -d, then this "global" database will be used in read-only
              mode in conjunction with the read-write database specified with -d.  The -g  option
              can  be  used a second time to specify a third database, which will also be used in
              read-only mode.  Again, the filename can optionally be prefixed with a  TYPE  which
              specifies the database type.

       -P, --plain-map FILE
              Maintain a mapping of all database tokens to their non-hashed counterparts in FILE,
              one token per line.  This can be useful if you want to be able to list the contents
              of  your database at a later date, for instance to get a list of email addresses in
              your allow-list.  Note that using this option may slow qsf down, and  only  entries
              written to the database while this option is active will be stored in FILE.

       -s, --subject
              Rewrite the Subject line of any email that turns out to be spam, adding "[SPAM]" to
              the start of the line.

       -S, --subject-marker SUBJECT
              Instead of adding "[SPAM]", add SUBJECT to the Subject line of any email that turns
              out to be spam.  Implies -s.

       -H, --header-marker MARK
              Instead of setting the X-Spam header to "YES", set it to MARK if email turns out to
              be spam.  This can be useful if your email client can only search all headers for a
              string,  rather than one particular header (so searching for "YES" might match more
              than just the output of qsf).

       -n, --no-header
              Do not add an X-Spam header to messages.

       -r, --add-rating
              Insert an additional header X-Spam-Rating which is a rating of the "spamminess"  of
              a message from 0 to 100; 90 and above are counted as spam, anything under 90 is not
              considered spam.  If combined with -t, then the rating (0-100) will be  output,  on
              its own, on standard output.

       -A, --asterisk
              Insert  an  additional  header  X-Spam-Level  which  will  contain between 0 and 20
              asterisks (*), depending on the spam rating.

       -t, --test
              Instead of passing the message out on standard output, output nothing, and  exit  0
              if the message is not spam, or exit 1 if the message is spam.  If combined with -r,
              then the spam rating will be output on standard output.

       -a, --allowlist
              Enable the allow-list.  This causes the email  addresses  given  in  the  message's
              "From:"  and  "Return-Path:"  headers  to  be checked against a list; if either one
              matches, then the message is always treated as non-spam,  regardless  of  what  the
              token  database  says.  When specified with a retraining flag, -a -m (mark as spam)
              will remove that address from the allow-list as well  as  marking  the  message  as
              spam,  and -a -M (mark as non-spam) will add that address to the allow-list as well
              as marking the message as non-spam.  The idea is that you add all of  your  friends
              to the allow-list, and then none of their messages ever get marked as spam.

       -y, --denylist
              Enable  the  deny-list.   This  causes  the  email addresses given in the message's
              "From:" and "Return-Path:" headers to be checked against a second list;  if  either
              one  matches,  then  theh message is always treated as spam.  Training works in the
              same way as with -a, except that you must specify -m or  -M  twice  to  modify  the
              deny-list instead of the allow-list, and with the reverse syntax: -y -m -m (mark as
              spam) will add that address to the deny-list, whereas -y -M -M (mark  as  non-spam)
              will  remove that address from the deny-list.  This double specification is so that
              the usual retraining process never touches the deny-list; the deny-list  should  be
              carefully maintained rather than automatically generated.

              Normally you would not need to use the deny-list.

       -L, --level, --threshold LEVEL
              Change  the  spam  scoring threshold level which must be reached before an email is
              classified as spam.  The default is 90.

       -Q, --min-tokens NUM
              Only give a score if more than NUM tokens are found in the message - otherwise  the
              message  is assumed to be non-spam, and it is not modified in any way.  The default
              is 0.  This option might be useful if you find that very short messages  are  being
              frequently miscategorised.

       -e, --email, --email-only EMAIL
              Query  or  update  the allow-list entry for the email address EMAIL.  With no other
              options, this will simply output "YES" if EMAIL is in the allow-list, or "NO" if it
              is not. With -t, it will not output anything, but will exit 0 (success) if EMAIL is
              in the allow-list, or 1 (failure) if it is not. With the -m (mark-spam) option, any
              previous  allow-list  entry  for EMAIL will be removed. Finally, with the -M (mark-
              nonspam) option, EMAIL will be added to the allow-list if it is not already on it.

              If EMAIL is just the word MSG on its own, then an email will be read from  standard
              input, and the email addresses given in the "From:" and "Return-Path:" headers will
              be used.

              Using -e automatically switches on -a.

              If you also specify -y, then the deny-list will be operated on.  Remember  that  -m
              and -M are reversed with the deny-list.

              If  you  specify  an email address of the form @domain (nothing before the @), then
              the whole domain will be allow or deny listed.

       -v, --verbose
              Add extra X-QSF-Info headers to any filtered email, containing error  messages  and
              so on if applicable.  Specify -v more than once to increase verbosity.

       -T, --train SPAM NONSPAM [MAXROUNDS]
              Train  the  database  using  the two mbox folders SPAM and NONSPAM, by testing each
              message  in  each  folder  and  updating  the  database  each  time  a  message  is
              miscategorised.   This is done several times, and may take a while to run.  Specify
              the -a (allow-list) flag to add every sender in the NONSPAM folder to  your  allow-
              list as a side-effect of the training process.  If MAXROUNDS is specified, training
              will end after this number of rounds if the results are still not good enough.  The
              default is a maximum of 200 rounds.

       -m, --mark-spam
              Instead  of  passing  the message out on standard output, mark its contents as spam
              and update the database accordingly.   If  the  allow-list  (-a)  is  enabled,  the
              message's "From:" and "Return-Path:" addresses are removed from the allow-list.  If
              the deny-list (-y) is enabled and you specify -m twice, the message's addresses are
              added to the deny-list instead.

       -M, --mark-nonspam
              Instead  of  passing  the message out on standard output, mark its contents as non-
              spam and update the database accordingly.  If the allow-list (-a) is  enabled,  the
              message's "From:" and "Return-Path:" addresses are added to the allow-list (see the
              -a option above).  If the deny-list (-y) is enabled and you specify -M  twice,  the
              message's addresses are removed from the deny-list instead.

       -w, --weight WEIGHT
              When  marking  as  spam or non-spam, update the database with a weighting of WEIGHT
              per token instead of the default of 1.   Useful  when  correcting  mistakes,  eg  a
              message  that  has  been  mistakenly  detected as spam should be marked as non-spam
              using a weighting of 2, i.e. double the usual weighting, to counteract the error.

       -D, --dump [FILE]
              Dump the contents of the database as a platform-independent text file, suitable for
              archival,  transfer to another machine, and so on.  The data is output on stdout or
              into the given FILE.

       -R, --restore [FILE]
              Rebuild the database from scratch from the text file on stdin.  If a FILE is given,
              data is read from there instead of from stdin.

       -O, --tokens
              Instead  of  filtering,  output a list of the tokens found in the message read from
              standard input, along with the number of times each token was found.  This is  only
              useful if you want to use qsf as a general tokeniser for use with another filtering
              package.

       -E, --merge OTHERDB
              Merge the OTHERDB database into the current database.  This can be  useful  if  you
              want to take one user's mailbox and merge it into the system-wide one, for instance
              (this would be done by, as root, doing qsf -d /var/lib/qsfdb  -E  /home/user/.qsfdb
              and then removing /home/user/.qsfdb).

       -B, --benchmark SPAM NONSPAM [MAXROUNDS]
              Benchmark  the  training  process  using  the two mbox folders SPAM and NONSPAM.  A
              temporary database is created and trained using the first 75% of  the  messages  in
              each  folder, and then the entire contents of each folder is tested to see how many
              false positives  and  false  negatives  occur.  Some  timing  information  is  also
              displayed.

              This  can be used to decide which backend is best on your system.  Use -d to select
              a backend, eg qsf -B spam nonspam -d GDBM - this will create a  temporary  database
              which is removed afterwards.

              The  exception  to  this  is the MySQL backend, where a full database specification
              must be given (-d MySQL:database=db;host=localhost;...)   and  the  database  table
              given will not be wiped beforehand or dropped afterwards.

              As  with  -T,  if MAXROUNDS is specified, training will never be done for more than
              this number of rounds; the default is 200.

       -h, --help
              Print a usage message on standard output and exit successfully.

       -V, --version
              Print version information, including a list  of  available  database  backends,  on
              standard output and exit successfully.

DEPRECATED OPTIONS

       The  following  options  are only for use with the old binary tree database backend or old
       databases that haven't been upgraded to the new format that came in with version 1.1.0.

       -N, --no-autoprune
              When marking as spam or nonspam, never automatically prune the  database.   Usually
              the database is pruned after every 500 marks; if you would rather --prune manually,
              use -N to disable automatic pruning.

       -p, --prune
              Remove redundant entries from the database and clean  it  up  a  little.   This  is
              automatically done after several calls to --mark-spam or --mark-nonspam, and during
              training with --train if the training takes a large number of rounds, so it  should
              rarely   be   necessary  to  use  --prune  manually  unless  you  are  using  -N  /
              --no-autoprune.

       -X, --prune-max NUM
              When the database is being pruned, no more than NUM entries will be considered  for
              removal.   This  is  to  prevent  CPU  and  memory resources being taken over.  The
              default is 100,000 but in some circumstances (if you find that  pruning  takes  too
              long) this option may be used to reduce it to a more manageable number.

FILES

       /var/lib/qsfdb
              The  default  (system-wide) spam database.  If you wish to install qsf system-wide,
              this should be read-only to everyone; there should be one user  with  write  access
              who  can update the spam database with qsf --mark-spam and qsf --mark-non-spam when
              necessary.

       /var/lib/qsfdb2
              A second, read-only, system-wide database. This can be useful when  installing  qsf
              system-wide  and using third-party spam databases; the first global database can be
              updated with system-specific changes, and this second database can be  periodically
              updated when the third-party spam database is updated.

       $HOME/.qsfdb
              The  default  spam  database  for per-user data.  Users without write access to the
              system-wide database will have their data written here, and the two databases  will
              be read together.  The per-user database will be given a weighting equivalent to 10
              times the weighting of the global database.

NOTES

       Currently, you cannot use qsf to check for spam while the database is being updated.  This
       means that while an update is in progress, all email is passed through as non-spam.

       There is an upper size limit of 512Kb on incoming email; anything larger than this is just
       passed through as non-spam, to avoid tying up machine resources.

       The plaintext token mapping maintained by --plain-map will never shrink, only grow.  It is
       intended  for  use by housekeeping and user interface scripts that, for instance, the user
       can use to list all email addresses on their allow-list.  These scripts should  take  care
       of weeding out entries for tokens that are no longer in the database.  If you have no such
       scripts, there is probably no point in using --plain-map anyway.

       Avoid using the deny-list (-y) in any automated retraining, as it can be cause the  filter
       to  reject  mail  unnecessarily.   In  general  the deny-list is probably best left unused
       unless explicitly required by your particular setup.

       If both the allow-list and the deny-list are enabled, then email addresses will  first  be
       checked  against  the deny-list, then the allow-list, then the domain of the email address
       will be checked for matching "@domain" entries in the deny-list and  then  in  the  allow-
       list.

EXAMPLES

       To  filter all of your mail through qsf, with the allow-list enabled and the "spam rating"
       header being added, add this to your .procmailrc file:

               :0 wf
               | qsf -ra

       If you want qsf to add "[SPAM]" to the subject line of any messages it thinks are spam, do
       this instead:

               :0 wf
               | qsf -sra

       To  automatically  mark  any  email  sent  to  spambox@yourdomain.com as spam (this is the
       "naive" version):

               :0 H
               * ^To:.*spambox@yourdomain.com
               | qsf -am

       To do the same, but cleverly, so that only email to spambox@yourdomain.com which qsf  does
       NOT  already classify as spam gets marked as spam in the database (this stops the database
       getting too heavily weighted):

               # If sent to spambox@yourdomain.com:
               :0
               * ^To:.*spambox@yourdomain.com
               {
                  :0 wf
                  | qsf -a

                  # The above two lines can be skipped if you've
                  # already piped the message through qsf.

                  # If the qsf database says it's not spam,
                  # mark it as spam!
                  :0 H
                  * ^X-Spam: NO
                  | qsf -am
               }

       Remove the -a option in the above examples if you don't want to use the allow-list.

       A more complicated filtering example - this will only run qsf on messages which don't have
       a  subject line saying "your <something> is on fire" and which don't have a sender address
       ending in "@foobar.com", meaning that messages with  that  subject  line  OR  that  sender
       address will NEVER be marked as spam, no matter what:

               :0 wf
               * ! ^Subject: Your .* is on fire
               * ! ^From: .*@foobar.com
               | qsf -ra

       For more on procmail(1) recipes, see the procmailrc(5) and procmailex(5) manual pages.

       A couple of macros to add to your .muttrc file, if you use mutt(1) as a mail user agent:

               # Press F5 to mark a message as spam and delete it
               macro index <f5> "<pipe-message>qsf -am\n<delete-message>"
               macro pager <f5> "<pipe-message>qsf -am\n<delete-message>"

               # Press F9 to mark a message as non-spam
               macro index <f9> "<pipe-message>qsf -aM\n"
               macro pager <f9> "<pipe-message>qsf -aM\n"

       Again, remove the -a option in the above examples if you don't want to use the allow-list.

       Note,  however,  that  the  above  macros  won't  work  when  operating on multiple tagged
       messages. For that, you'd need something like this:

               macro  index  <f5>  ":set   pipe_split\n<tag-prefix><pipe-message>qsf   -am\n<tag-
              prefix><delete-message>\n:unset pipe_split\n"

       If  you  use  qmail(7),  then  to get procmail working with it you will need to put a line
       containing just DEFAULT=./Maildir/ at the top of your ~/.procmailrc file, so that procmail
       delivers to your Maildir folder instead of trying to deliver to /var/spool/mail/$USER, and
       you will need to put this in your ~/.qmail file:

               | preline procmail

       This will cause all your mail to be delivered via  procmail  instead  of  being  delivered
       directly into your mail directory.

       See the qmail(7) documentation for more about mail delivery with qmail.

       If you use postfix(1), you can set up a system-wide mail filter by creating a user account
       for the purpose of filtering mail, populating that account's .qsfdb, and then  creating  a
       shell  script,  to  run  as  that  user,  which  runs  qsf  on  stdin and passes stdout to
       sendmail(8).

       Doing this requires some knowledge of postfix configuration and care needs to be taken  to
       avoid  mail  loops.  One qsf user's full HOWTO is included in the doc/ directory with this
       package.

THE ALLOW-LIST

       A feature called the "allow-list" can be switched on by specifying the --allowlist  or  -a
       option.   This causes messages' "From:" and "Return-Path:" addresses to be checked against
       a list of people you have said to allow all messages from, and if a message's  "From:"  or
       "Return-Path:" address is in the list, it is never marked as spam.  This means you can add
       all your friends to an "allow-list" and qsf will then never mis-file their  messages  -  a
       quick  way  to  do this is to use -a with -T (train); everyone in your non-spam folder who
       has sent you an email will be added to the allow-list automatically during training.

       You can manually add and remove addresses to and from the allow-list using the -e  (email)
       option. For instance, to add foo@bar.com to the allow-list, do this:

               qsf -e foo@bar.com -M

       To remove bad@nasty.com from the allow-list, do this:

               qsf -e bad@nasty.com -m

       And to see whether someone@somewhere.com is in the allow-list or not, just do this:

               qsf -e someone@somewhere.com

       In  general,  you  probably always want to enable the allow-list, so always specify the -a
       option when using qsf.  This will automatically maintain the allow-list based on what  you
       classify as spam or non-spam.

       The  only times you might want to turn it off are when people on your allow-list are prone
       to getting viruses or if a virus is causing email to be sent to you that is pretending  to
       be from someone on your allow-list.

BACKUP AND RESTORE

       Because  the  database format is platform-specific, it is a good idea to periodically dump
       the database to a text file using qsf -D so that, if necessary, it can be  transferred  to
       another machine and restored with qsf -R later on.

       Also  note  that  since  the  actual  contents  of  email messages are never stored in the
       database (see TECHNICAL DETAILS), you can safely share your qsf database  with  friends  -
       simply dump your database to a file, like this:

               qsf -D > your-database-dump.txt

       Once you have sent your-database-dump.txt to another person, they can do this:

               qsf -R < your-database-dump.txt

       They will then have an identical database to yours.

TECHNICAL DETAILS

       When  a  message  is  passed  to  qsf,  any attachments are decoded, all HTML elements are
       removed, and the message text is then broken up into "tokens", where a "token" is a single
       word  or  URL.  Each token is hashed using the MD5 algorithm (see below for why), and that
       hash is then used to look up each token in the qsf database.

       For full details of which parts of an email (headers, body, attachments, etc) are used  to
       calculate the spam rating, see the TOKENISATION section below.

       Within  the  database,  each token has two numbers associated with it: the number of times
       that token has been seen in spam, and the number of times it has been  seen  in  non-spam.
       These  two  numbers,  along  with the total number of spam and non-spam messages seen, are
       then used to give a "spamminess" value for that particular token.  This "spamminess" value
       ranges  from  "definitely  not  spammy"  at one end of the scale, through "neutral" in the
       middle, up to "definitely spammy" at the other end.

       Once a "spamminess" value has been calculated for all of the  tokens  in  the  message,  a
       summary calculation is made to give an overall "is this spam?"  probability rating for the
       message.  If the overall probability is 0.9 or above, the message is flagged as spam.

       In addition to the probability test is the "allow-list".  If enabled (with the -a option),
       the  whole  probability  check  is  skipped  if the sender of the message is listed in the
       allow-list, and the message is not marked as spam.

       When training the database, a message is split up into tokens as described above, and then
       the  numbers  in  the  database for each token are simply added to: if you tell qsf that a
       message is spam, it adds one to the "number of times seen in spam" counter for each token,
       and if you tell it a message is not spam, it adds one to the "number of times seen in non-
       spam" counter for each token.  If you specify a weight,  with  -w,  then  the  number  you
       specify is added instead of one.

       To  stop the database growing uncontrollably, the database keeps track of when a token was
       last used.  Underused tokens are automatically removed from the database.  (The old method
       was to "prune" every 500 updates).

       Finally,  the  reason  MD5  hashes  were  used  is privacy.  If the actual tokens from the
       messages, and the actual email addresses in the allow-list, were  stored,  you  could  not
       share  a  single  qsf  database between multiple users because bits of everyone's messages
       would be in the database - things like emailed passwords, keywords  relating  to  personal
       gossip,  and  so  on.  So a hash is stored instead.  A hash is a "one-way" function; it is
       easy to turn a token into a hash but very hard (some might say impossible) to turn a  hash
       back  into  the token that created it.  This means that you end up with a database with no
       personal information in it.

TOKENISATION

       When a message is broken up into tokens, various parts  of  the  message  are  treated  in
       different ways.

       First,  all header fields are discarded, except for the important ones: From, Return-Path,
       Sender, To, Reply-To, and Subject.

       Next, any MIME-encoded attachments are decoded.  Any attachments whose  MIME  type  starts
       with "text/" (i.e. HTML and text) are tokenised, after having any HTML tags stripped.  Any
       non-textual attachments are  replaced  with  their  MD5  hash  (such  that  two  identical
       attachments will have the same hash), and that hash is then used as a token.

       In  addition  to single-word tokens from textual message parts, qsf adds doubled-up tokens
       so that word pairs get added to the database.   This  makes  the  database  a  bit  bigger
       (although the automatic pruning tends to take care of that) but makes matching more exact.

SPECIAL FILTERS

       As  well  as  using  the  textual  content  of email to detect spam, qsf also uses special
       filters which create "pseudo-tokens" based on various rules.   This  means  that  specific
       patterns, not just individual words, can be used to determine whether a message is spam or
       not.

       For example,  if  a  message  contains  lots  of  words  with  multiple  consonants,  like
       "ashjkbnxcsdjh",  then  each  time a word like that is seen the special token ".GIBBERISH-
       CONSONANTS." is added to the list of tokens found in the message.  If it  turns  out  that
       most  messages with words that trigger this filter rule are spam, then other messages with
       gibberish consonant strings will be more likely to be flagged as spam.

       Currently the special filters are:

       GTUBE  Flags any message containing the string XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-
              ANTI-UBE-TEST-EMAIL*C.34X  as  spam - useful for testing that your qsf installation
              is working.

       ATTACH-SCR

       ATTACH-PIF

       ATTACH-EXE

       ATTACH-VBS

       ATTACH-VBA

       ATTACH-LNK

       ATTACH-COM

       ATTACH-BAT
              Adds a token for every attachment whose filename ends in  ".scr",  ".pif",  ".exe",
              ".vbs", ".vba", ".lnk", ".com", and ".bat" respectively (these are often viruses).

       ATTACH-GIF

       ATTACH-JPG

       ATTACH-PNG
              Adds a token for every attachment whose filename ends in ".gif", ".jpg" or ".jpeg",
              and ".png" respectively.

       ATTACH-DOC

       ATTACH-XLS

       ATTACH-PDF
              Adds a token for every attachment whose filename ends in ".doc", ".xls", or  ".pdf"
              respectively (these tend to indicate a non-spam email).

       SINGLE-IMAGE
              Adds a token if the message contains exactly one attached image.

       MULTIPLE-IMAGES
              Adds a token if the message contains more than one attached image.

       GIBBERISH-CONSONANTS
              Adds  a  token  for  every  word  found  that  has multiple consonants in a row, as
              described above.  Spam often contains strings of gibberish.

       GIBBERISH-VOWELS
              Adds a token  for  every  word  found  that  has  multiple  vowels  in  a  row,  eg
              "aeaiaiaeeio".

       GIBBERISH-FROMCONS
              Like GIBBERISH-CONSONANTS, but only for the "From:" and "Return-Path:" addresses on
              their own.

       GIBBERISH-FROMVOWL
              Like GIBBERISH-VOWELS, but only for the "From:"  and  "Return-Path:"  addresses  on
              their own.

       GIBBERISH-BADSTART
              Adds a token for every word that starts with a bad character such as %.

       GIBBERISH-HYPHENS
              Adds a token for every word with more than three hyphens or underscores in it.

       GIBBERISH-LONGWORDS
              Adds a token for every word with over 30 characters in it (but less than 60).

       HTML-COMMENTS-IN-WORDS
              Adds  a  token  for  every  HTML comment found in the middle of a word.  Spam often
              contains HTML inside words, like this: w<!--dsgfhsdgjgh-->ord

       HTML-EXTERNAL-IMG
              Adds a token for every HTML <img> (image) tag found that  contains  ://  (i.e.   it
              refers to an external image).

       HTML-FONT
              Adds a token for every HTML <font> tag found.

       HTML-IP-IN-URLS
              Adds a token for every URL found containing an IP address.

       HTML-INT-IN-URL
              Adds a token for every URL found containing an integer in its hostname.

       HTML-URLENCODED-URL
              Adds a token for every URL found containing a % sign in its hostname.

       Normally,  filters  will just cause a token to be added, and these tokens are processed by
       the normal weighting algorithm.  However  the  GTUBE  filter  will  immediately  flag  any
       matching message as spam, bypassing the token matching.

DATABASE BACKENDS

       The inbuilt "list" database backend will not necessarily provide the best performance, but
       is provided because using it requires no external libraries.

       If, when qsf was compiled, the correct libraries were available, then it will be  possible
       to  use  qsf  with  alternative  database  backends.   To find out which backends you have
       available, run qsf -V (capital V) and read the second line of output.  To see how  well  a
       backend  performs,  collect  some spam and non-spam and use qsf -d BACKEND -B SPAM NONSPAM
       (see the entry for -B above).

       Some people find that they get the best performance out of the gdbm  backend;  this  is  a
       library that is widely available on many systems.

       To  efficiently  share  a  qsf  database  across multiple machines, you may find the MySQL
       backend useful.  However, using it is a little more complicated.

       To use the MySQL backend you will need to create a  table  with  the  fields  key1,  key2,
       token,  value1,  value2  and value3.  The token, value1, value2, and value3 fields must be
       VARCHAR(64), BIGINT or INT, and BIGINT or INT respectively,  and  indexing  on  the  token
       field is a good idea. The key1 and key2 fields can be anything, but they must be present.

       For example:

                USE mydatabase;
                CREATE TABLE qsfdb (
                  key1      BIGINT UNSIGNED NOT NULL,
                  key2      BIGINT UNSIGNED NOT NULL,
                  token     VARCHAR(64) DEFAULT '' NOT NULL,
                  value1    INT UNSIGNED NOT NULL,
                  value2    INT UNSIGNED NOT NULL,
                  value3    INT UNSIGNED NOT NULL,
                  PRIMARY KEY (key1,key2,token),
                  KEY (key1),
                  KEY (key2),
                  KEY (token)
                );

       The  key1  and  key2  fields  allow  you  to  have multiple qsf databases in one table, by
       specifying different key1 and key2 values on invocation.

       Instead of specifying a database file with the --database / -d option,  you  must  specify
       either  a specification string as described below, or the name of a file containing such a
       string on its first line.

       The specification string is as follows:

                database=DATABASE;host=HOST;port=PORT;
                user=USER;pass=PASS;table=TABLE;
                key1=KEY1;key2=KEY2

       This string must be all on one line, with no spaces.

       DATABASE
              is the name of the MySQL database.

       HOST   is the hostname of the database server (eg "localhost").

       PORT   is the TCP port to connect on (eg 3306).

       USER   is the username to connect with.

       PASS   is the password to connect with.

       TABLE  is the database table to use.  If a table with this name does not exist when qsf is
              called  in  update  or  training mode, then it will be created if permissions allow
              this to be done.

       KEY1   is the value to use for the key1 field.

       KEY2   is the value to use for the key2 field.

       Since command lines can be seen in the process list, it is  probably  best  to  specify  a
       filename (eg qsf -d mysql:qsfdb.spec) and put the specification string inside that file.

TROUBLESHOOTING

       If  you  have problems with qsf, please check the list below; if this does not help, go to
       the qsf home page and investigate the mailing lists, or email the author.

       Nothing is being marked as spam.
              First, use the -r option to switch on the X-Spam-Rating header, and check that this
              header appears in email passed through qsf.  If it does not, then it is likely that
              qsf is not being run at all -  check  your  configuration  of  procmail(1)  or  its
              equivalent.

              If  you  are  seeing  X-Spam-Rating  headers,  and  different emails have different
              scores, then you may simply need to retrain your database a little more.  Take more
              spam email and pass it to qsf -m.

              If  you  are  seeing  X-Spam-Rating headers but they all give the same spam rating,
              then the most likely reason is that qsf is not reading  any  database.   Make  sure
              that whatever is processing the email has read permissions on /var/lib/qsfdb and/or
              ~/.qsfdb - and make sure that, if  you  are  using  ~/.qsfdb,  what  your  database
              creator  thought  was ~ ($HOME) is the same as it is for whatever is processing the
              email.

       Retraining sometimes takes a very long time.
              With the obtree backend or 2-column MySQL or SQLite tables, every 500th retrain (-m
              or  -M),  the  database  is  pruned.   On some systems this may take some time, and
              during this time the database is locked (except when  using  the  MySQL  or  SQLite
              backends).   If  you constantly do a lot of retraining and want to avoid this, then
              use the -N option to  suppress  auto-pruning,  and  then  have  a  cron(8)  job  or
              something run a manual prune (qsf -p) every now and again.

       Running qsf from procmail fails with an error.
              If  you  can  run  qsf from the command line, but in your procmail log file you get
              errors  about  "qsf:  cannot  execute  binary  file",  then  contact  your   system
              administrator  for  help.  It  may be that incoming email is handled by a different
              server to the one you normally shell into, and  either  they  are  of  a  different
              architecture  or  operating  system, or the mail server is not permitted to execute
              user-owned binaries.

ACKNOWLEDGEMENTS

       The following people have contributed suggestions, comments, patches, and testing:

              Tom Parker <http://www.bits.bris.ac.uk/palfrey/>
              Dr Kelly A. Parker
              Vesselin Mladenov <http://www.antipodes.bg/>
              Glyn Faulkner
              Mark Reynolds
              Sam Roberts
              Scott Allen
              Karsten Kankowski
              M. Kolbl
              Micha Holzmann
              Jef Poskanzer <http://www.acme.com/jef/>
              Clemens Fischer <http://ino-waiting.gmxhome.de/>
              Nelson A. de Oliveira
              Michal Vitecek
              Tommy Pettersson <http://www.lysator.liu.se/~ptp/>

AUTHOR

       The author:

              Andrew Wood <andrew.wood@ivarch.com>
              http://www.ivarch.com/

       Project home page:

              http://www.ivarch.com/programs/qsf/

BUGS

       If you find any bugs, please contact the author, either by email or by using  the  contact
       form on the web site.

SEE ALSO

       procmail(1), procmailrc(5), procmailex(5)

       Someone has written a guide to using qsf with KMail that can be found at:
       http://www.softwaredesign.co.uk/Information.SpamFilters.html

LICENSE

       This is free software, distributed under the ARTISTIC 2.0 license.