GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DOVECOT-ANTISPAM (7)

NAME

dovecot-antispam - The dovecot plugin for spam systems training.

CONTENTS

Disclaimer
Description
Folder Matrix
Backends
     Mailtrain
     Spool2dir
     Dspam
     Crm114
     Signature-log
Installation
Configuration
     Parameter Types
     Global Options
     Folder Options
     Signature Engine Options
     Mailtrain Specific Options
     Spool2dir Specific Options
     Dspam Specific Options
     Crm114 Specific Options
     Signature-log Specific Options
Allowing Appends
Authors
     Original Authors
     This Fork Author And Maintainer

DISCLAIMER

This is the fork of the antispam dovecot plugin as the original one is aimed for dovecot versions before 2.0 and the respectful authors weren’t going to update it.

You can find the original version at http://johannes.sipsolutions.net/Projects/dovecot-antispam

Even though most of the things were adopted, some things did change. Please read this manual carefully. You have been warned.

DESCRIPTION

The dovecot antispam plugin is aimed to help in spam systems training. Consider the following scenario. Your mailbox is flooded with tons of mail. They are delivered to the configured folders based on the arbitrary spam system judgement. This judgement is not always correct or not always what you would like it to be, however. This is where this plugin comes into play.

All you have to do is move the mail into the correct folder. All the rest in order to let the spam system know it made an error will be done automatically by this plugin.

It watches for when you move the mail to some folder and acts accordingly. The advantage of this approach is that the mail ends up in the right target folder directly and needs not be touched twice.

FOLDER MATRIX

This plugin has internally four types of folders. Different actions are programmed when you move the mail from one folder to the other. The following table describes the actions depending on the source and destination folders.



        ┏━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━┓
        ┃ dst╲src ┃ SPAM ┃ TRASH ┃ UNSURE ┃ OTHER ┃
        ┣━━━━━━━━━╋━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━┩
        ┃   SPAM  ┃  /   │   /   │   -    │   -   │
        ┣━━━━━━━━━╉──────┼───────┼────────┼───────┤
        ┃  TRASH  ┃  /   │   /   │   *    │   /   │
        ┣━━━━━━━━━╉──────┼───────┼────────┼───────┤
        ┃ UNSURE  ┃  *   │   *   │   *    │   *   │
        ┣━━━━━━━━━╉──────┼───────┼────────┼───────┤
        ┃  OTHER  ┃  +   │   /   │   +    │   /   │
        ┗━━━━━━━━━┹──────┴───────┴────────┴───────┘

Legend:
/ move is ignored
* move is forbidden
- classify as spam
+ classify as ham

BACKENDS

The plugin supports multiple backends, for different kinds of spam systems.

    MAILTRAIN

This backend is aimed to send mail to some e-mail address for retraining. Which makes it very fast to set up if you already have a working setup that uses training addresses as recommended by many spam systems.

Since this backend simply pipes the message to an external program it can also be used for all kinds of other spam systems with help of the wrapper to make all the work for you. E.g. for spamassassin you can call sa-learn or spamc.

    SPOOL2DIR

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 appropriately. You can, for example, use incron to pick up new mail from those files.

    DSPAM

This backend instantly retrains by calling dspam client with appropriate arguments. There is an ability to circumvent mail retraining based on an arbitrary header (configurable) value.

    CRM114

This backend instantly retrains by calling mailreaver.crm script. The command line argument --good or --spam (by default) is given depending on how the 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.

    SIGNATURE-LOG

This backend collects the information about the mails in the dovecot dictionary incrementing the value of the name-value pair each time the message is retrained as spam and decrementing each time otherwise. Further processing of the dictionary contents is left to be the user’s responsibility.

INSTALLATION

Open your dovecot configuration file (usually /etc/dovecot/dovecot.conf) and add the antispam plugin to the imap protocol section:



        protocol imap {
            mail_plugins = $mail_plugins antispam
        }

CONFIGURATION

All of the run-time configuration options shown below are to be put into the plugin section of the dovecot configuration file.

    PARAMETER TYPES

string Case-sensitive string;
istring Case-insensitive string;
lstring Case-sensitive string list, semicolon separated;
ilstring Case-insensitive string list, semicolon separated;
boolean Case-insensitive boolean (YES/NO);

    GLOBAL OPTIONS

antispam_backend (istring) Selects the specific backend to be used for spam system training. Obligatory, default = NONE.
antispam_allow_append_to_spam (boolean) Specifies whether to allow appending mails to the spam folder from the unknown source. See the ALLOWING APPENDS section below for the details on why it is not advised to turn this option on. Optional, default = NO.
antispam_skip_from_line (boolean) Specifies whether to skip the leading "From " line of the mail piped to the backend processor. Optional, default = NO.

    FOLDER OPTIONS

You must configure the list for at least one of the SPAM, TRASH, and UNSURE folders using the following parameters. By default all of them are unset. The order of precedence is: SPAM, TRASH, UNSURE, i.e. if you put the same folder name into TRASH and UNSURE then the folder is considered to be TRASH.
antispam_spam, antispam_trash, antispam_unsure (lstring) static lists to match the folder names literally case sensitive.
antispam_spam_pattern, antispam_trash_pattern, antispam_unsure_pattern (lstring) wildcard lists to match the beginning of the folder names. I.e. wildcard could be specified in the end only. Identical to the static lists otherwise.
antispam_spam_pattern_ignorecase, antispam_trash_pattern_ignorecase, antispam_unsure_pattern_ignorecase (ilstring) same as the previous, but case insensitive.

    SIGNATURE ENGINE OPTIONS

Several backends are based on the signature header processing.
antispam_signature (string) header name to extract the mail signature from. Obligatory, default = NONE.
antispam_signature_missing (istring) specifies what to do if the signature header is missing. Possible values: "move" (move the mail silently without training), "error" (display an error stating that the signature header is missing). Optional, default = "error".

    MAILTRAIN SPECIFIC OPTIONS

antispam_mail_sendmail (string) specifies the binary to execute. Obligatory, default = NONE.
antispam_mail_sendmail_args (lstring) specifies the arguments to be passed to the binary in the command line. Optional, default = NONE.
antispam_mail_spam (string) specifies the final command line argument in case when processed mail is SPAM. Obligatory, default = NONE.
antispam_mail_notspam (string) specifies the final command line argument in case when processed mail is not SPAM. Obligatory, default = NONE.

    SPOOL2DIR SPECIFIC OPTIONS

Both options below must have "%%lu" specified with any legal C modifier two times. The first one is replaced with the current time (epoch). The second one is replaced with the incrementing counter to make sure the file name is unique.
antispam_spool2dir_spam (string) filename template with full path for mails marked as SPAM. Obligatory, default = NONE.
antispam_spool2dir_notspam (string) filename template with full path for mails marked as not SPAM. Obligatory, default = NONE.

    DSPAM SPECIFIC OPTIONS

This backend is based on the signature engine.
antispam_dspam_binary (string) specifies the path to the dspam client binary. Optional, default = "/usr/bin/dspam".
antispam_dspam_args (lstring) list of command line arguments to the dspam binary. Must include one "%%s" in order to be replaced with the signature value. Optional, default = "--source=error;--signature=%%s".
antispam_dspam_spam (string) command line argument to specify that mail should be reclassified as SPAM. Optional, default = "--class=spam".
antispam_dspam_notspam (string) command line argument to specify that mail should be reclassified as not SPAM. Optional, default = "--class=innocent".
antispam_dspam_result_header (string) specifies the mail header name to derive the classification result. Optional, default = NONE.
antispam_dspam_result_blacklist (ilstring) specifies the list of classification results to avoid retraining for. Optional, default = NONE.

    CRM114 SPECIFIC OPTIONS

This backend is based on the signature engine.
antispam_crm_binary (string) specifies the path to the mailreaver.crm script. Optional, default = "/usr/share/crm114/mailreaver.crm".
antispam_crm_args (lstring) list of command line arguments to the mailreaver.crm script. Optional, default = NONE.
antispam_crm_spam (string) command line argument to specify that mail should be reclassified as SPAM. Optional, default = "--spam".
antispam_crm_notspam (string) command line argument to specify that mail should be reclassified as not SPAM. Optional, default = "--good".

    SIGNATURE-LOG SPECIFIC OPTIONS

This backend is based on the signature engine.
antispam_siglog_dict_uri (string) specifies the URI of the dovecot dictionary to connect to. Obligatory, default = NONE.
antispam_siglog_dict_user (string) specifies the user credentials used to connect to the dovecot dictionary. Obligatory, default = NONE.

ALLOWING APPENDS

By appends we mean the case of mail moving when the source folder is unknown, e.g. when you move from some other account or with tools like offlineimap. 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 and be trained. However, because the plugin cannot know the source of the message (it is assumed to be from OTHER folder), multiple bad scenarios can happen:
1. SPAM --> SPAM transitions cannot be recognised and are trained;
2. TRASH --> SPAM transitions cannot be recognised and are trained;
3. SPAM --> not-SPAM transitions cannot be recognised therefore training good messages will never work with APPENDs.

AUTHORS

    ORIGINAL AUTHORS

Original authors of the dovecot-antispam plugin for dovecot versions prior to 2.0.
o Johannes Berg;
o Frank Cusack;
o Benedikt Boehm;
o Andreas Schneider.

    THIS FORK AUTHOR AND MAINTAINER

o Eugene Paskevich <eugene@raptor.kiev.ua>.
Search for    or go to Top of page |  Section 7 |  Main Index


dovecot-antispam DOVECOT-ANTISPAM (7) 03 April 2016

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.