From 1343231466748a2186028c07a109e139cbeb87a6 Mon Sep 17 00:00:00 2001
From: Johannes Berg <johannes@sipsolutions.net>
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