From 1343231466748a2186028c07a109e139cbeb87a6 Mon Sep 17 00:00:00 2001 From: Johannes Berg Date: Mon, 15 Oct 2007 15:39:41 +0200 Subject: make manual page out of README --- README | 162 +---------------------------------------------------------------- 1 file changed, 1 insertion(+), 161 deletions(-) (limited to 'README') diff --git a/README b/README index 328ef0f..903a0ef 100644 --- a/README +++ b/README @@ -1,161 +1 @@ -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 +Use 'man ./antispam.7' -- cgit v1.2.3