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 +---------------------------------------------------------- antispam.7 | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+), 161 deletions(-) create mode 100644 antispam.7 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' diff --git a/antispam.7 b/antispam.7 new file mode 100644 index 0000000..8fe3e63 --- /dev/null +++ b/antispam.7 @@ -0,0 +1,165 @@ +.TH ANTISPAM 7 "15 October 2007" \*(eX +.SH NAME +antispam \- The dovecot antispam plugin. + +.SH 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: +.IP " 1." 4 +moving mail out of the SPAM folder and +.IP " 2." 4 +moving mail into the SPAM folder. + +.PP +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. + +.SH 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: + +.nf +protocol imap { + mail_plugins = antispam + # mail_plugin_dir = /usr/lib/dovecot/modules/imap +} +.fi + +.SH BACKENDS + +The plugin supports multiple backends, there are currently two working +backends included in the distribution: + +.SS 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 + +.SS 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. + +.SS 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. + + +.SH CONFIGURATION + +Aside from the build-configuration done in the `.config' file, you have +the following run-time options (shown along with the default): + +.nf +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 +} +.fi + +.SH AUTHORS + +Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider -- cgit v1.2.3