path: root/README

NAME

    The dovecot antispam pugin.

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 two 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

    email sender backend (spam filter agnostic)

        This backend sends mail to ham@example.com or spam@example.com
        (actual addresses are configurable) for retraining. This backend can
        be very fast to set up if you already have a working setup that uses
        training addresses as recommended by many spam filter setups.

    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-exec approach.


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

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

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

        # semicolon-separated list of spam folders
        antispam_spam = SPAM

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

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

        #===================
        # dspam-exec 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 = --user;%u  # % expansion done by dovecot
        # antispam_dspam_args = --mode=teft

        #=====================
        # mail sending plugin

        # temporary directory
        antispam_mail_tmpdir = /tmp

        # spam/not-spam addresses (default unset which will give errors)
        # antispam_mail_spam =
        # antispam_mail_ham =

        # sendmail binary
        antispam_mail_tmpdir = /usr/sbin/sendmail

        #===================
        # crm114-exec 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
    }

AUTHORS

    Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider