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 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.
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-exec 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
# 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 "Gelöschte "
# match is _case_senstive_!
#
# antispam_trash_pattern_ignorecase = deleted *;Gel&APY-schte *
# match any folders that start with "deleted " or "gelöschte "
# match is _case_insenstive_, except the non-USASCII letters,
# "ö" in this example.
# To match the upper-case Ö, 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-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 = --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
#=====================
# mail sending plugin
#
# Because of the way this plugin works, you can also use it
# to train via an arbitrary program that receives the message
# on standard input, in that case you can use the config
# options antispam_mail_spam and antispam_mail_notspam for
# the argument that distinguishes between ham and spam.
# For example:
# antispam_mail_sendmail = /path/to/mailtrain
# antispam_mail_sendmail_args = --for;%u
# antispam_mail_spam = --spam
# antispam_mail_notspam = --ham
# will call it, for example, like this:
# /path/to/mailtrain --for jberg --spam
# temporary directory
antispam_mail_tmpdir = /tmp
# spam/not-spam addresses (default unset which will give errors)
# antispam_mail_spam =
# antispam_mail_notspam =
# sendmail binary
antispam_mail_sendmail = /usr/sbin/sendmail
#antispam_mail_sendmail_args = -f;%u@example.com # % expansion done by dovecot
#===================
# 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
#===================
# 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)