Provided by: dovecot-antispam_1.4~rc3-1_i386 bug

NAME

       antispam - The dovecot antispam plugin.

DESCRIPTION

       The  dovecot antispam plugin watches a defined spam folder (defaults to
       "SPAM"). It works together with a  spam  system  that  classifies  each
       message  as it is delivered. When the message is classified as spam, it
       shall be delivered to  the  spam  folder,  otherwise  via  the  regular
       filtering  file  the user may have (maildrop, sieve, ...). Now the user
       has  everything  classified  as  spam  in  the  special  spam   folder,
       everything else where it should be sorted to.

       This  is  not  enough  because  our  spam scanner needs training. We'll
       occasionally have false positives and false negatives. Now this is  the
       point  where  the  dovecot  antispam plugin comes into play. Instead of
       moving mail into special folders or forwarding  them  to  special  mail
       addresses for retraining, the plugin offers two actions for the user:

        1. moving mail out of the SPAM folder and

        2. moving mail into the SPAM folder.

       The  dovecot  plugin  watches these actions (and additionally prohibits
       APPENDs to the SPAM folder, more for technical reasons than others) and
       tells  the  spam  classifier  that  it  made  an error and needs to re-
       classify the message (as spam/not spam depending on which  way  it  was
       moved.)

       The  advantage  of  this approach is that the mail ends up in the right
       target folder directly and needs not be touched twice.

       When other classifiers like crm114 that  have  an  `unsure'  state  are
       used, the plugin can also help, it supports an `unsure' folder feature.
       The unsure folder cannot be written to, but moving out from there  into
       a folder that is considered a spam folder will learn as spam, any other
       folder (except trashes) will cause learning as not-spam.

INSTALLATION

       First copy the `defconfig' file to `.config' and edit it as  necessary.
       You  need  to  have  the  dovecot  headers installed and possibly other
       things depending on the backend you choose.  Then,  assuming  you  have
       configured the INSTALLDIR correctly, simply run `make install'.

       If  you  do  not wish to use the install target, simply copy the plugin
       (that is, the  file  lib90_antispam_plugin.so)  to  your  dovecot  imap
       plugin  directory; by default this is /usr/lib/dovecot/modules/imap/ or
       any dir you have configured (look for the mail_plugin_dir configuration
       directive.)

       Open       your      dovecot      configuration      file      (usually
       /etc/dovecot/dovecot.conf) and add the  antispam  plugin  to  the  imap
       protocol section:

       protocol imap {
           mail_plugins = antispam
           # mail_plugin_dir = /usr/lib/dovecot/modules/imap
       }

BACKENDS

       The  plugin  supports  multiple  backends,  there  are  currently a few
       working backends included in the distribution:

   dspam executable backend (dspam specific)
       This backend instantly  retrains  by  calling  dspam.  There  are  some
       problems  with  this  approach  including  (1)  it can take a long time
       during which the IMAP session is blocked (2) when  many  users  retrain
       many messages at once server load may spike

   pipe backend (spam filter agnostic)
       This  backend  simply pipes the mail to train to a process it executes.
       This can for example be used to send it as email to  mail  aliases  for
       retraining. This backend can be very easy to set up if you already have
       a working setup that uses training addresses  as  recommended  by  many
       spam filter setups.

       Since  this  backend  simply pipes the message to a program (by default
       sendmail) it can also be used for all kinds of other spam filters,  for
       example spamassassin (by calling sa-learn instead of sendmail.)

   crm114 executable backend (crm114 specific)
       This  backend  instantly retrains by calling mailreaver.crm which needs
       to be configured (defaulting to /bin/false!); the  argument  --good  or
       --spam is given depending on how mail is moved.

       You need to use the unsure folder option (see below) together with this
       plugin and deliver unsure mail into an unsure folder, spam mail into  a
       spam folder and other mail regularly.

       Has the same drawbacks as the dspam approach.

   spool2dir backend (general)
       This  backend  spools the message into a file. No further processing is
       performed. You need to write an extra daemon that picks up the  spooled
       files  and trains the spam filter as appropriate. You can, for example,
       use incron to pick up new emails.

CONFIGURATION

       Aside from the build-configuration done in the `.config' file, you have
       the following run-time options (shown along with the default):

       plugin {
           ##################
           # GENERIC OPTIONS

           # backend selection, MUST be configured first,
           # there's no default so you need to set one of
           # these options:
           # antispam_backend = crm114
           # antispam_backend = dspam
           # antispam_backend = pipe
           # antispam_backend = spool2dir

           # mail signature (used with any backend requiring a signature)
           antispam_signature = X-DSPAM-Signature

           # action to take on mails without signature
           # (used with any backend requiring a signature)
           # (we recommend only setting this to 'move' after verifying that the
           # whole setup is working)
           # antispam_signature_missing = move # move silently without training
           antispam_signature_missing = error

           # The list of folders for trash, spam and unsure can be given
           # with three options, e.g. "trash" matches the given folders
           # exactly as written, "trash_pattern" accept the * wildcard at
           # the end of the foldername, "trash_pattern_ignorecase"
           # accepts the * wildcard at the end of the foldername _and_
           # matches the name case insensitivly.

           # the *-wildcard with the following meaning:
           #    * at the end: any folder that _start_ with the string
           # e.g.:
           #     antispam_trash_pattern = deleted *;Gel&APY-schte *
           # match any folders that start with "deleted " or "Geloschte "
           # match is _case_senstive_!
           #
           #     antispam_trash_pattern_ignorecase = deleted *;Gel&APY-schte *
           # match any folders that start with "deleted " or "geloschte "
           # match is _case_insenstive_, except the non-USASCII letters,
           # "o" in this example.
           # To match the upper-case O, too, you need to add yet another
           # pattern "gel&ANY-schte *", note the different UTF7 encoding:
           # &ANY- instead of &APY-.

           # semicolon-separated list of Trash folders (default unset i.e. none)
           # antispam_trash =
           # antispam_trash = trash;Trash;Deleted Items; Deleted Messages
           # antispam_trash_pattern = trash;Trash;Deleted *
           # antispam_trash_pattern_ignorecase = trash;Deleted *

           # semicolon-separated list of spam folders
           antispam_spam = SPAM
           # antispam_spam_pattern = SPAM
           # antispam_spam_pattern_ignorecase = SPAM

           # semicolon-separated list of unsure folders (default unset i.e. none)
           # antispam_unsure =
           # antispam_unsure_pattern =
           # antispam_unsure_pattern_ignorecase =

           # Whether to allow APPENDing to SPAM folders or not. Must be set to
           # "yes" (case insensitive) to be activated. Before activating, please
           # read the discussion below.
           # antispam_allow_append_to_spam = no

           ###########################
           # BACKEND SPECIFIC OPTIONS
           #

           #===================
           # dspam plugin

           # dspam binary
           antispam_dspam_binary = /usr/bin/dspam

           # semicolon-separated list of extra arguments to dspam
           # (default unset i.e. none)
           # antispam_dspam_args =
           # antispam_dspam_args = --deliver=;--user;%u  # % expansion done by dovecot
           # antispam_dspam_args = --mode=teft

           # Ignore mails where the DSPAM result header contains any of the
           # strings listed in the blacklist
           # (default unset i.e. none)
           # antispam_dspam_result_header = X-DSPAM-Result
           # semicolon-separated list of blacklisted results, case insensitive
           # antispam_dspam_result_blacklist = Virus

           #=====================
           # pipe plugin
           #
           # This plug can be used to train via an arbitrary program that
           # receives the message on standard input. Since sendmail can be
           # such a program, it can be used to send the message to another
           # email address for training there.
           #
           # For example:
           #   antispam_pipe_program = /path/to/mailtrain
           #        (defaults to /usr/sbin/sendmail)
           #   antispam_pipe_program_args = --for;%u
           #   antispam_pipe_program_spam_arg = --spam
           #   antispam_pipe_program_notspam_arg = --ham
           #   antispam_pipe_tmpdir = /tmp
           # will call it, for example, like this:
           #   /path/to/mailtrain --for jberg --spam
           #
           # The old configuration options from when this plugin was called
           # "mailtrain" are still valid, these are, in the same order as
           # above: antispam_mail_sendmail, antispam_mail_sendmail_args,
           # antispam_mail_spam, antispam_mail_notspam and antispam_mail_tmpdir.

           # temporary directory
           antispam_pipe_tmpdir = /tmp

           # spam/not-spam argument (default unset which will is not what you want)
           # antispam_pipe_program_spam_arg =
           # antispam_pipe_program_notspam_arg =

           # binary to pipe mail to
           antispam_pipe_program = /usr/sbin/sendmail
           #antispam_pipe_program_args = -f;%u@example.com # % expansion done by dovecot

           #===================
           # crm114 plugin

           # mailreaver binary
           antispam_crm_binary = /bin/false
           # antispam_crm_binary = /usr/share/crm114/mailreaver.crm

           # semicolon-separated list of extra arguments to dspam
           # (default unset i.e. none)
           # antispam_crm_args =
           # antispam_crm_args = --config=/path/to/config

           # NOTE: you need to set the signature for this backend
           antispam_signature = X-CRM114-CacheID

           #===================
           # spool2dir plugin

            # spam/not-spam spool2dir drop (default unset which will give errors)
            # The first %%lu is replaced by the current time.
            # The second %%lu is replaced by a counter to generate unique names.
            # These two tokens MUST be present in the template! However
            # you can insert any C-style modifier as shown.
            # antispam_spool2dir_spam    = /tmp/spamspool/%%020lu-%u-%%05lus
            # antispam_spool2dir_notspam = /tmp/spamspool/%%020lu-%u-%%05luh
       }

ALLOWING APPENDS?

       You should be careful with allowing APPENDs to SPAM folders. The reason
       for possibly allowing it is to allow not-SPAM --> SPAM  transitions  to
       work  with  offlineimap. However, because with APPEND the plugin cannot
       know the source of the message, multiple bad scenarios can happen:

        1. SPAM --> SPAM transitions cannot be recognised and are trained

        2. the same holds for Trash --> SPAM transitions

       Additionally,  because  we   cannot   recognise   SPAM   -->   not-SPAM
       transitions, training good messages will never work with APPEND.

AUTHORS

       Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider

                                15 October 2007                    ANTISPAM(7)